Readded erroneously deleted {END} tag and doublechecked {(F,U,X)*}-{END} tag balancing. Minor documentation cleanup. No changes to code. (CVS 5271)

FossilOrigin-Name: b55590501b5b5ada4e22d790e1a36b532de7deb7

1 files changed, 63 insertions, 67 deletions

diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 44d5250f7..b6fdd5926 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -30,7 +30,7 @@
 ** the version number) and changes its name to "sqlite3.h" as
 ** part of the build process.
 **
-** @(#) $Id: sqlite.h.in,v 1.350 2008/06/22 09:55:14 mihailim Exp $
+** @(#) $Id: sqlite.h.in,v 1.351 2008/06/22 10:21:27 mihailim Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@@ -725,7 +725,7 @@ typedef struct sqlite3_mutex sqlite3_mutex;
 ** {F11141} SQLite will guarantee that the zFilename string passed to
 ** xOpen() is a full pathname as generated by xFullPathname() and
 ** that the string will be valid and unchanged until xClose() is
-** called.  {END} So the [sqlite3_file] can store a pointer to the
+** called. {END}  So the [sqlite3_file] can store a pointer to the
 ** filename if it needs to remember the filename for some reason.
 **
 ** {F11142} The flags argument to xOpen() includes all bits set in
@@ -767,24 +767,25 @@ typedef struct sqlite3_mutex sqlite3_mutex;
 ** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
 ** deleted when it is closed.  {F11146} The [SQLITE_OPEN_DELETEONCLOSE]
 ** will be set for TEMP  databases, journals and for subjournals.
+**
 ** {F11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
 ** for exclusive access.  This flag is set for all files except
-** for the main database file. {END}
+** for the main database file.
 **
 ** {F11148} At least szOsFile bytes of memory are allocated by SQLite
 ** to hold the  [sqlite3_file] structure passed as the third
-** argument to xOpen.  {END}  The xOpen method does not have to
+** argument to xOpen. {END}  The xOpen method does not have to
 ** allocate the structure; it should just fill it in.
 **
 ** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
 ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
-** to test whether a file is at least readable.  {END} The file can be a
+** to test whether a file is at least readable. {END}  The file can be a
 ** directory.
 **
 ** {F11150} SQLite will always allocate at least mxPathname+1 bytes for the
 ** output buffer xFullPathname. {F11151} The exact size of the output buffer
-** is also passed as a parameter to both  methods. {END} If the output buffer
+** is also passed as a parameter to both  methods. {END}  If the output buffer
 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
 ** handled as a fatal error by SQLite, vfs implementations should endeavor
 ** to prevent this by setting mxPathname to a sufficiently large value.
@@ -829,13 +830,13 @@ struct sqlite3_vfs {
 **
 ** {F11191} These integer constants can be used as the third parameter to
 ** the xAccess method of an [sqlite3_vfs] object. {END}  They determine
-** what kind of permissions the xAccess method is
-** looking for.  {F11192} With [SQLITE_ACCESS_EXISTS], the xAccess method
-** simply checks to see if the file exists. {F11193} With
-** SQLITE_ACCESS_READWRITE, the xAccess method checks to see
-** if the file is both readable and writable.  {F11194} With
-** SQLITE_ACCESS_READ the xAccess method
-** checks to see if the file is readable.
+** what kind of permissions the xAccess method is looking for.
+** {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method
+** simply checks whether the file exists.
+** {F11193} With SQLITE_ACCESS_READWRITE, the xAccess method
+** checks whether the file is both readable and writable.
+** {F11194} With SQLITE_ACCESS_READ, the xAccess method
+** checks whether the file is readable.
 */
 #define SQLITE_ACCESS_EXISTS    0
 #define SQLITE_ACCESS_READWRITE 1
@@ -1607,7 +1608,7 @@ void sqlite3_free_table(char **result);
 ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
 ** results into memory obtained from [sqlite3_malloc()].
 ** The strings returned by these two routines should be
-** released by [sqlite3_free()].   Both routines return a
+** released by [sqlite3_free()].  Both routines return a
 ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
 ** memory to hold the resulting string.
 **
@@ -1675,8 +1676,7 @@ void sqlite3_free_table(char **result);
 ** The %Q option works like %q except it also adds single quotes around
 ** the outside of the total string.  Additionally, if the parameter in the
 ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
-** single quotes) in place of the %Q option. {END}  So, for example,
-** one could say:
+** single quotes) in place of the %Q option.  So, for example, one could say:
 **
 ** <blockquote><pre>
 **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
@@ -2194,12 +2194,11 @@ void *sqlite3_profile(sqlite3*,
 **          argument to sqlite3_progress_handler().
 **
 ** {F12914} The fourth argument to sqlite3_progress_handler() is a
-***         void pointer passed to the progress callback
+**          void pointer passed to the progress callback
 **          function each time it is invoked.
 **
-** {F12915} If a call to [sqlite3_step()] results in fewer than
-**          N opcodes being executed,
-**          then the progress callback is never invoked. {END}
+** {F12915} If a call to [sqlite3_step()] results in fewer than N opcodes
+**          being executed, then the progress callback is never invoked.
 **
 ** {F12916} Every call to [sqlite3_progress_handler()]
 **          overwrites any previously registered progress handler.
@@ -2552,7 +2551,7 @@ int sqlite3_limit(sqlite3*, int id, int newVal);
 ** The second argument, "zSql", is the statement to be compiled, encoded
 ** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()
 ** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
-** use UTF-16.{END}
+** use UTF-16.
 **
 ** If the nByte argument is less than zero, then zSql is read up to the
 ** first zero terminator. If nByte is non-negative, then it is the maximum
@@ -2562,7 +2561,7 @@ int sqlite3_limit(sqlite3*, int id, int newVal);
 ** that the supplied string is nul-terminated, then there is a small
 ** performance advantage to be gained by passing an nByte parameter that
 ** is equal to the number of bytes in the input string <i>including</i>
-** the nul-terminator bytes.{END}
+** the nul-terminator bytes.
 **
 ** *pzTail is made to point to the first byte past the end of the
 ** first SQL statement in zSql.  These routines only compile the first
@@ -2583,7 +2582,7 @@ int sqlite3_limit(sqlite3*, int id, int newVal);
 ** for backwards compatibility, but their use is discouraged.
 ** In the "v2" interfaces, the prepared statement
 ** that is returned (the [sqlite3_stmt] object) contains a copy of the
-** original SQL text. {END} This causes the [sqlite3_step()] interface to
+** original SQL text. This causes the [sqlite3_step()] interface to
 ** behave a differently in two ways:
 **
 ** <ol>
@@ -2595,7 +2594,7 @@ int sqlite3_limit(sqlite3*, int id, int newVal);
 ** return [SQLITE_SCHEMA].  But unlike the legacy behavior, [SQLITE_SCHEMA] is
 ** now a fatal error.  Calling [sqlite3_prepare_v2()] again will not make the
 ** error go away.  Note: use [sqlite3_errmsg()] to find the text
-** of the parsing error that results in an [SQLITE_SCHEMA] return. {END}
+** of the parsing error that results in an [SQLITE_SCHEMA] return.
 ** </li>
 **
 ** <li>
@@ -3231,7 +3230,7 @@ const char *sqlite3_column_decltype(sqlite3_stmt*,int);
 const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
 
 /*
-** CAPI3REF:  Evaluate An SQL Statement {F13200}
+** CAPI3REF: Evaluate An SQL Statement {F13200}
 **
 ** After a [prepared statement] has been prepared using either
 ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
@@ -3422,7 +3421,7 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
 **
 ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
 ** even empty strings, are always zero terminated.  The return
-** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
+** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary
 ** pointer, possibly even a NULL pointer.
 **
 ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
@@ -3516,7 +3515,7 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
 ** The pointers returned are valid until a type conversion occurs as
 ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
 ** [sqlite3_finalize()] is called.  The memory space used to hold strings
-** and blobs is freed automatically.  Do <b>not</b> pass the pointers returned
+** and BLOBs is freed automatically.  Do <b>not</b> pass the pointers returned
 ** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
 ** [sqlite3_free()].
 **
@@ -4358,7 +4357,7 @@ void sqlite3_result_zeroblob(sqlite3_context*, int n);
 ** The remaining arguments to the application-supplied routine are two strings,
 ** each represented by a (length, data) pair and encoded in the encoding
 ** that was passed as the third argument when the collation sequence was
-** registered. {END} The application defined collation routine should
+** registered. {END}  The application defined collation routine should
 ** return negative, zero or positive if the first string is less than,
 ** equal to, or greater than the second string. i.e. (STRING1 - STRING2).
 **
@@ -4525,7 +4524,7 @@ int sqlite3_rekey(
 );
 
 /*
-** CAPI3REF:  Suspend Execution For A Short Time {F10530}
+** CAPI3REF: Suspend Execution For A Short Time {F10530}
 **
 ** The sqlite3_sleep() function causes the current thread to suspend execution
 ** for at least a number of milliseconds specified in its parameter.
@@ -4552,7 +4551,7 @@ int sqlite3_rekey(
 int sqlite3_sleep(int);
 
 /*
-** CAPI3REF:  Name Of The Folder Holding Temporary Files {F10310}
+** CAPI3REF: Name Of The Folder Holding Temporary Files {F10310}
 **
 ** If this global variable is made to point to a string which is
 ** the name of a folder (a.k.a. directory), then all temporary files
@@ -4573,7 +4572,7 @@ SQLITE_EXTERN char *sqlite3_temp_directory;
 **
 ** The sqlite3_get_autocommit() interface returns non-zero or
 ** zero if the given database connection is or is not in autocommit mode,
-** respectively.   Autocommit mode is on by default.
+** respectively.  Autocommit mode is on by default.
 ** Autocommit mode is disabled by a [BEGIN] statement.
 ** Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].
 **
@@ -4598,7 +4597,7 @@ SQLITE_EXTERN char *sqlite3_temp_directory;
 **          statement.
 **
 ** LIMITATIONS:
-***
+**
 ** {U12936} If another thread changes the autocommit status of the database
 **          connection while this routine is running, then the return value
 **          is undefined.
@@ -4606,7 +4605,7 @@ SQLITE_EXTERN char *sqlite3_temp_directory;
 int sqlite3_get_autocommit(sqlite3*);
 
 /*
-** CAPI3REF:  Find The Database Handle Of A Prepared Statement {F13120}
+** CAPI3REF: Find The Database Handle Of A Prepared Statement {F13120}
 **
 ** The sqlite3_db_handle interface returns the [database connection] handle
 ** to which a [prepared statement] belongs.  The database handle returned by
@@ -4623,7 +4622,7 @@ int sqlite3_get_autocommit(sqlite3*);
 sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
 
 /*
-** CAPI3REF:  Find the next prepared statement {F13140}
+** CAPI3REF: Find the next prepared statement {F13140}
 **
 ** This interface returns a pointer to the next [prepared statement] after
 ** pStmt associated with the [database connection] pDb.  If pStmt is NULL
@@ -4788,7 +4787,7 @@ void *sqlite3_update_hook(
 );
 
 /*
-** CAPI3REF:  Enable Or Disable Shared Pager Cache {F10330}
+** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330}
 ** KEYWORDS: {shared cache} {shared cache mode}
 **
 ** This routine enables or disables the sharing of the database cache
@@ -4833,15 +4832,14 @@ void *sqlite3_update_hook(
 int sqlite3_enable_shared_cache(int);
 
 /*
-** CAPI3REF:  Attempt To Free Heap Memory {F17340}
+** CAPI3REF: Attempt To Free Heap Memory {F17340}
 **
-** The sqlite3_release_memory() interface attempts to
-** free N bytes of heap memory by deallocating non-essential memory
-** allocations held by the database library. {END}  Memory used
-** to cache database pages to improve performance is an example of
-** non-essential memory.  Sqlite3_release_memory() returns
-** the number of bytes actually freed, which might be more or less
-** than the amount requested.
+** The sqlite3_release_memory() interface attempts to free N bytes
+** of heap memory by deallocating non-essential memory allocations
+** held by the database library. {END}  Memory used to cache database
+** pages to improve performance is an example of non-essential memory.
+** sqlite3_release_memory() returns the number of bytes actually freed,
+** which might be more or less than the amount requested.
 **
 ** INVARIANTS:
 **
@@ -4856,7 +4854,7 @@ int sqlite3_enable_shared_cache(int);
 int sqlite3_release_memory(int);
 
 /*
-** CAPI3REF:  Impose A Limit On Heap Size {F17350}
+** CAPI3REF: Impose A Limit On Heap Size {F17350}
 **
 ** The sqlite3_soft_heap_limit() interface places a "soft" limit
 ** on the amount of heap memory that may be allocated by SQLite.
@@ -5048,16 +5046,16 @@ int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
 **
 ** This API can be invoked at program startup in order to register
 ** one or more statically linked extensions that will be available
-** to all new [database connections].
-**
-** This interface is experimental and is subject to change or
-** removal in future releases of SQLite.
+** to all new [database connections]. {END}
 **
 ** This routine stores a pointer to the extension in an array that is
 ** obtained from [sqlite3_malloc()].  If you run a memory leak checker
 ** on your program and it reports a leak because of this array, invoke
 ** [sqlite3_reset_auto_extension()] prior to shutdown to free the memory.
 **
+** This interface is experimental and is subject to change or
+** removal in future releases of SQLite.
+**
 ** INVARIANTS:
 **
 ** {F12641} This function registers an extension entry point that is
@@ -5078,8 +5076,9 @@ int sqlite3_auto_extension(void *xEntryPoint);
 /*
 ** CAPI3REF: Reset Automatic Extension Loading {F12660}
 **
-** This function disables all previously registered automatic extensions.
-** It undoes the effect of all prior [sqlite3_auto_extension()] calls.
+** This function disables all previously registered automatic
+** extensions. {END}  It undoes the effect of all prior
+** [sqlite3_auto_extension()] calls.
 **
 ** This interface is experimental and is subject to change or
 ** removal in future releases of SQLite.
@@ -5089,7 +5088,7 @@ int sqlite3_auto_extension(void *xEntryPoint);
 ** {F12661} This function disables all previously registered
 **          automatic extensions.
 **
-** {F12662} This function disabled automatic extensions in all threads.
+** {F12662} This function disables automatic extensions in all threads.
 */
 void sqlite3_reset_auto_extension(void);
 
@@ -5383,7 +5382,7 @@ typedef struct sqlite3_blob sqlite3_blob;
 /*
 ** CAPI3REF: Open A BLOB For Incremental I/O {F17810}
 **
-** This interfaces opens a handle to the BLOB located
+** This interfaces opens a [BLOB handle | handle] to the BLOB located
 ** in row iRow, column zColumn, table zTable in database zDb;
 ** in other words, the same BLOB that would be selected by:
 **
@@ -5438,7 +5437,7 @@ int sqlite3_blob_open(
 );
 
 /*
-** CAPI3REF:  Close A BLOB Handle {F17830}
+** CAPI3REF: Close A BLOB Handle {F17830}
 **
 ** Closes an open [BLOB handle].
 **
@@ -5458,9 +5457,8 @@ int sqlite3_blob_open(
 **
 ** INVARIANTS:
 **
-** {F17833} The [sqlite3_blob_close(P)] interface closes an
-**          [sqlite3_blob] object P previously opened using
-**          [sqlite3_blob_open()].
+** {F17833} The [sqlite3_blob_close(P)] interface closes an [sqlite3_blob]
+**          object P previously opened using [sqlite3_blob_open()].
 **
 ** {F17836} Closing an [sqlite3_blob] object using
 **          [sqlite3_blob_close()] shall cause the current transaction to
@@ -5532,7 +5530,7 @@ int sqlite3_blob_bytes(sqlite3_blob *);
 int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
 
 /*
-** CAPI3REF:  Write Data Into A BLOB Incrementally {F17870}
+** CAPI3REF: Write Data Into A BLOB Incrementally {F17870}
 **
 ** This function is used to write data into an open [BLOB handle] from a
 ** caller-supplied buffer. N bytes of data are copied from the buffer Z
@@ -5584,7 +5582,7 @@ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
 int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
 
 /*
-** CAPI3REF:  Virtual File System Objects {F11200}
+** CAPI3REF: Virtual File System Objects {F11200}
 **
 ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
 ** that SQLite uses to interact
@@ -5691,7 +5689,7 @@ int sqlite3_vfs_unregister(sqlite3_vfs*);
 ** <li>  SQLITE_MUTEX_STATIC_PRNG
 ** <li>  SQLITE_MUTEX_STATIC_LRU
 ** <li>  SQLITE_MUTEX_STATIC_LRU2
-** </ul> {END}
+** </ul>
 **
 ** {F17015} The first two constants cause sqlite3_mutex_alloc() to create
 ** a new mutex.  The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
@@ -5715,7 +5713,7 @@ int sqlite3_vfs_unregister(sqlite3_vfs*);
 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
 ** returns a different mutex on every call.  {F17034} But for the static
 ** mutex types, the same mutex is returned on every call that has
-** the same type number. {END}
+** the same type number.
 **
 ** {F17019} The sqlite3_mutex_free() routine deallocates a previously
 ** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every
@@ -5836,14 +5834,12 @@ struct sqlite3_mutex_methods {
 ** defined and if NDEBUG is not defined.
 **
 ** {F17083} These routines should return true if the mutex in their argument
-** is held or not held, respectively, by the calling thread. {END}
+** is held or not held, respectively, by the calling thread.
 **
 ** {X17084} The implementation is not required to provided versions of these
-** routines that actually work.
-** If the implementation does not provide working
-** versions of these routines, it should at least provide stubs
-** that always return true so that one does not get spurious
-** assertion failures. {END}
+** routines that actually work. If the implementation does not provide working
+** versions of these routines, it should at least provide stubs that always
+** return true so that one does not get spurious assertion failures.
 **
 ** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then
 ** the routine should return 1.  {END} This seems counter-intuitive since
@@ -5861,7 +5857,7 @@ int sqlite3_mutex_notheld(sqlite3_mutex*);
 ** CAPI3REF: Mutex Types {F17001}
 **
 ** {F17002} The [sqlite3_mutex_alloc()] interface takes a single argument
-** which is one of these integer constants. {END}
+** which is one of these integer constants.
 */
 #define SQLITE_MUTEX_FAST             0
 #define SQLITE_MUTEX_RECURSIVE        1