Improved documentation for sqlite3_reset(), in response to

[forum:/forumpost/a72bab3dea|forum post a72bab3dea].

FossilOrigin-Name: 1dfeb3dceee8f30daf5462683f264b9de23e7068e036e70b11ee1b608ac2f7fa

manifest

@@ -1,5 +1,5 @@
-C sqlite3.oo1.Stmt.reset()\snow\sthrows\sif\ssqlite3_reset()\sreturns\snon-zero,\sanalog\sto\s[f23eb5c6d365].
-D 2023-05-19T16:34:56.463
+C Improved\sdocumentation\sfor\ssqlite3_reset(),\sin\sresponse\sto\n[forum:/forumpost/a72bab3dea|forum\spost\sa72bab3dea].
+D 2023-05-19T16:42:49.388
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -638,7 +638,7 @@ F src/resolve.c 3e53e02ce87c9582bd7e7d22f13f4094a271678d9dc72820fa257a2abb5e4032
 F src/rowset.c ba9515a922af32abe1f7d39406b9d35730ed65efab9443dc5702693b60854c92
 F src/select.c 0937f89a8a020833eaca73a8c9e7661bfbf9b52905520a77993b9ce683dfbccb
 F src/shell.c.in 2c8cc2a0b01daf00767b53bb073324e2a0ce50df6c01dc751389403100b9ef1d
-F src/sqlite.h.in c14a4471fcd897a03631ac7ad3d05505e895e7b6419ec5b96cae9bc4df7a9fc6
+F src/sqlite.h.in 8e0265e42d7695d86a0b8c7de9979e6c29edc2c616fa5eea11b682a6af838c7c
 F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
 F src/sqlite3ext.h da473ce2b3d0ae407a6300c4a164589b9a6bfdbec9462688a8593ff16f3bb6e4
 F src/sqliteInt.h a3ced8b9ebc573189c87b69f24bf10d2b9cd3cefefaae52623a2fa79e6fdd408
@@ -2070,8 +2070,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P d29d62cf7658aeb49f3c8a5d0b0809d945ebc9b79379a255eb88f771d2a2c430
-R 53d02ec9bf9fe6dde03ebd8441ab452e
-U stephan
-Z e3f35152f6937f75344c962f4f8fbb12
+P 487ae12c9a21e5862bd590bbb1030c39734657d52136cf67b98c7545e6ecbe1c
+R 39b64ba449418cb0ab801f0a9bec4df8
+U drh
+Z 46fed3a751762448fe0476ef3a96f8d1
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-487ae12c9a21e5862bd590bbb1030c39734657d52136cf67b98c7545e6ecbe1c
+1dfeb3dceee8f30daf5462683f264b9de23e7068e036e70b11ee1b608ac2f7fa

src/sqlite.h.in

@@ -5260,14 +5260,26 @@ int sqlite3_finalize(sqlite3_stmt *pStmt);
 ** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
 ** back to the beginning of its program.
 **
-** ^If the most recent call to [sqlite3_step(S)] for the
-** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
-** or if [sqlite3_step(S)] has never before been called on S,
-** then [sqlite3_reset(S)] returns [SQLITE_OK].
+** ^The return code from [sqlite3_reset(S)] indicates whether or not
+** the previous evaluation of prepared statement S completed successfully.
+** ^If [sqlite3_step(S)] has never before been called on S or if
+** [sqlite3_step(S)] has not been called since the previous call
+** to [sqlite3_reset(S)], then [sqlite3_reset(S)] will return
+** [SQLITE_OK].
 **
 ** ^If the most recent call to [sqlite3_step(S)] for the
 ** [prepared statement] S indicated an error, then
 ** [sqlite3_reset(S)] returns an appropriate [error code].
+** ^The [sqlite3_reset(S)] interface might also return an [error code]
+** if there were no prior errors but the process of resetting
+** the prepared statement caused a new error. ^For example, if an
+** [INSERT] statement with a [RETURNING] clause is only stepped one time,
+** that one call to [sqlite3_step(S)] might return SQLITE_ROW but
+** the overall statement might still fail and the [sqlite3_reset(S)] call
+** might return SQLITE_BUSY if locking constraints prevent the
+** database change from committing.  Therefore, it is important that
+** applications check the return code from [sqlite3_reset(S)] even if
+** no prior call to [sqlite3_step(S)] indicated a problem.
 **
 ** ^The [sqlite3_reset(S)] interface does not change the values
 ** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.