From c1975b6a6f3df98733bf36325b29148d42fced01 Mon Sep 17 00:00:00 2001 From: dan Date: Wed, 14 Jan 2026 17:02:22 +0000 Subject: [PATCH] Improve some of the documentation comments for the new code on this branch. FossilOrigin-Name: f352485db45a1280f91ec76f661b6dd50bb1d564b74bdff474c92e928860a47d --- ext/session/sqlite3session.c | 16 ++++++-------- ext/session/sqlite3session.h | 43 ++++++++++++++++++++---------------- manifest | 14 ++++++------ manifest.uuid | 2 +- 4 files changed, 39 insertions(+), 36 deletions(-) diff --git a/ext/session/sqlite3session.c b/ext/session/sqlite3session.c index a16254523c..2b0f5581ea 100644 --- a/ext/session/sqlite3session.c +++ b/ext/session/sqlite3session.c @@ -7036,7 +7036,7 @@ int sqlite3changegroup_change_text( } /* -** Configure the change currently under construction with a text value. +** Configure the change currently under construction with a blob value. */ int sqlite3changegroup_change_blob( sqlite3_changegroup *pGrp, @@ -7061,6 +7061,9 @@ int sqlite3changegroup_change_blob( return SQLITE_OK; } +/* +** Finish any change currently being constructed by the changegroup object. +*/ int sqlite3changegroup_change_finish( sqlite3_changegroup *pGrp, int bDiscard, @@ -7149,14 +7152,9 @@ int sqlite3changegroup_change_finish( } if( rc==SQLITE_OK ){ rc = sessionOneChangeToHash( - pGrp, - pGrp->cd.pTab, - pGrp->cd.eOp, - pGrp->cd.bIndirect, - pGrp->cd.pTab->nCol, - pGrp->cd.record.aBuf, - pGrp->cd.record.nBuf, - 0 + pGrp, pGrp->cd.pTab, + pGrp->cd.eOp, pGrp->cd.bIndirect, pGrp->cd.pTab->nCol, + pGrp->cd.record.aBuf, pGrp->cd.record.nBuf, 0 ); } } diff --git a/ext/session/sqlite3session.h b/ext/session/sqlite3session.h index 36dfc504e9..a5083e7706 100644 --- a/ext/session/sqlite3session.h +++ b/ext/session/sqlite3session.h @@ -1856,7 +1856,7 @@ int sqlite3session_config(int op, void *pArg); /* ** CAPI3REF: Configure a changegroup object ** -** Configure the changegroup object passes as the first argument. +** Configure the changegroup object passed as the first argument. ** At present the only valid value for the second parameter is ** [SQLITE_CHANGEGROUP_CONFIG_PATCHSET]. */ @@ -1865,12 +1865,12 @@ int sqlite3changegroup_config(sqlite3_changegroup*, int, void *pArg); /* ** CAPI3REF: Options for sqlite3changegroup_config(). ** -** The following values may passed as the the 2nd parameter to -** sqlite3session_object_config(). +** The following values may be passed as the 2nd parameter to +** sqlite3changegroup_config(). ** **
SQLITE_CHANGEGROUP_CONFIG_PATCHSET
** A changegroup object generates either a changeset or patchset. Usually, -** which is determined by whether the first call to sqlite3changegroup_add() +** this is determined by whether the first call to sqlite3changegroup_add() ** is passed a changeset or a patchset. Or, if the first changes are added ** to the changegroup object using the sqlite3changegroup_change_xxx() ** APIs, then this option may be used to configure whether the changegroup @@ -1880,8 +1880,8 @@ int sqlite3changegroup_config(sqlite3_changegroup*, int, void *pArg); ** type int. If the changegroup currently contains zero changes, and the ** value of the int variable is zero or greater than zero, then the ** changegroup is configured to generate a changeset or patchset, -** respectively. It is not an error if the changegroup is not configured -** because it has already started accumuting changes, just a no-op. +** respectively. It is a no-op, not an error, if the changegroup is not +** configured because it has already started accumulating changes. ** ** Before returning, the int variable is set to 0 if the changegroup is ** configured to generate a changeset, or 1 if it is configured to generate @@ -1917,7 +1917,7 @@ int sqlite3changegroup_config(sqlite3_changegroup*, int, void *pArg); ** bIndirect is non-zero) or not indirect (if bIndirect is zero). ** ** Following a successful call to this function, this function may not be -** called again on the same changegroup until after +** called again on the same changegroup object until after ** sqlite3changegroup_change_finish() has been called. Doing so is an ** SQLITE_MISUSE error. ** @@ -1928,7 +1928,11 @@ int sqlite3changegroup_config(sqlite3_changegroup*, int, void *pArg); ** table. If the changegroup object has not been configured with a schema for ** the specified table when this function is called, SQLITE_ERROR is returned. ** -** If successful, SQLITE_OK is returned. +** If successful, SQLITE_OK is returned. Otherwise, if an error occurs, an +** SQLite error code is returned. In this case, if argument pzErr is non-NULL, +** then (*pzErr) may be set to point to a buffer containing a utf-8 formated, +** nul-terminated, English language error message. It is the responsibility +** of the caller to eventually free this buffer using sqlite3_free(). */ int sqlite3changegroup_change_begin( sqlite3_changegroup*, @@ -1939,7 +1943,7 @@ int sqlite3changegroup_change_begin( ); /* -** This function may only be called between a succesful call to +** This function may only be called between a successful call to ** sqlite3changegroup_change_begin() and its matching ** sqlite3changegroup_change_finish() call. If it is called at any ** other time, it is an SQLITE_MISUSE error. Calling this function @@ -1964,8 +1968,8 @@ int sqlite3changegroup_change_begin( ** The fourth parameter is the integer value to use as part of the old.* or ** new.* record. ** -** If this call is successful, SQLITE_OK is returned. Otherwise, an SQLite -** error code. +** If this call is successful, SQLITE_OK is returned. Otherwise, if an +** error occurs, an SQLite error code is returned. */ int sqlite3changegroup_change_int64( sqlite3_changegroup*, @@ -2018,7 +2022,7 @@ int sqlite3changegroup_change_blob( ** discarded. In this case this function is always successful and SQLITE_OK ** returned. ** -** If paramter bDiscard is zero, then an attempt is made to add the current +** If parameter bDiscard is zero, then an attempt is made to add the current ** change to the changegroup. Assuming the changegroup is configured to ** produce a changeset (not a patchset), this requires that: ** @@ -2038,10 +2042,11 @@ int sqlite3changegroup_change_blob( ** ** * All values specified for PRIMARY KEY columns must be non-NULL. ** -** Otherwise, it is an error. If the changegroup already contains a -** change for the same row (identified by PRIMARY KEY columns), then the -** current change is combined with the existing change as for -** sqlite3changegroup_add(). +** Otherwise, it is an error. +** +** If the changegroup already contains a change for the same row (identified +** by PRIMARY KEY columns), then the current change is combined with the +** existing change in the same way as for sqlite3changegroup_add(). ** ** For a patchset, all of the above rules apply except that it doesn't matter ** whether or not values are provided for the non-PK old.* record columns @@ -2052,9 +2057,9 @@ int sqlite3changegroup_change_blob( ** If the call is successful, SQLITE_OK is returned. Otherwise, if an error ** occurs, an SQLite error code is returned. If an error is returned and ** parameter pzErr is not NULL, then (*pzErr) may be set to point to a buffer -** containing a nul-terminated utf-8 encoded English language error message. -** It is the responsibility of the caller to free any such error message -** buffer using sqlite3_free(). +** containing a nul-terminated, utf-8 encoded, English language error message. +** It is the responsibility of the caller to eventually free any such error +** message buffer using sqlite3_free(). */ int sqlite3changegroup_change_finish( sqlite3_changegroup*, diff --git a/manifest b/manifest index acfd050ffd..85952abefe 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Merge\slatest\strunk\schanges\sinto\sthis\sbranch. -D 2026-01-14T16:01:28.703 +C Improve\ssome\sof\sthe\sdocumentation\scomments\sfor\sthe\snew\scode\son\sthis\sbranch. +D 2026-01-14T17:02:22.575 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea @@ -578,8 +578,8 @@ F ext/session/sessionrowid.test 85187c2f1b38861a5844868126f69f9ec62223a03449a98a F ext/session/sessionsize.test 8fcf4685993c3dbaa46a24183940ab9f5aa9ed0d23e5fb63bfffbdb56134b795 F ext/session/sessionstat1.test 5e718d5888c0c49bbb33a7a4f816366db85f59f6a4f97544a806421b85dc2dec F ext/session/sessionwor.test 6fd9a2256442cebde5b2284936ae9e0d54bde692d0f5fd009ecef8511f4cf3fc -F ext/session/sqlite3session.c cad71a74f104fcdfc8eefaf544ea29f54c46a9a4d1a095b40d04824aa606f74a -F ext/session/sqlite3session.h cb6d25b573751afd9668f9ae8f1c7819df30916f43cc4c06b57749a6c2ce3e10 +F ext/session/sqlite3session.c 506f159483631ebe8885c304a59303f5c092ae92a915a7cb1cc2dc8a8acbced0 +F ext/session/sqlite3session.h b117cddb6ce93411b3b25c8a355d155a120e30efbdf506fc6899b71a333b0c56 F ext/session/test_session.c dae76c3da7eb51bc500451a37d23382f0d63f169927c5a26aee1db5a7dd6d91a F ext/wasm/GNUmakefile c3d007dd181527283d8674c812cc60518353f1f69c9a9d3008f10f53cea4a3c1 F ext/wasm/README-dist.txt f01081a850ce38a56706af6b481e3a7878e24e42b314cfcd4b129f0f8427066a @@ -2192,8 +2192,8 @@ F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee F tool/warnings.sh d924598cf2f55a4ecbc2aeb055c10bd5f48114793e7ba25f9585435da29e7e98 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f F tool/winmain.c 00c8fb88e365c9017db14c73d3c78af62194d9644feaf60e220ab0f411f3604c -P cd115f0f4437bf254058e40d70ba4e82e87227d2752695aa18f8431c3abc5c0b ed17a878e5a2e0cd1e9b69d528f5ac2ba8452d7c83deaf3cc72ecbff054f5ca3 -R f8b5009cc483f181e78204d06b24b034 +P fae9f376b74ae688dbdb5c0838a38427258d3d14c29c5346a3549e56db79961a +R b459bebcbcf7c8cf9788b1d94cb046aa U dan -Z fa614e954b104f0a1194ef8e1642c727 +Z 93999e32bda598fc2b940ad54d21c74f # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index 40aaf4dc5c..6f97ccae01 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -fae9f376b74ae688dbdb5c0838a38427258d3d14c29c5346a3549e56db79961a +f352485db45a1280f91ec76f661b6dd50bb1d564b74bdff474c92e928860a47d -- 2.47.3