Futher documentation refinements.

FossilOrigin-Name: 311c2eba93097bbecfa286bbeaff9bd6fc75a238e20cd2b6f834e594032d8c59

1 files changed, 16 insertions, 13 deletions

diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 0932a2cb2..53c037c3b 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -5573,11 +5573,15 @@ int sqlite3_create_window_function(
 ** </dd>
 **
 ** [[SQLITE_SUBTYPE]] <dt>SQLITE_SUBTYPE</dt><dd>
-** The SQLITE_SUBTYPE flag indicates to SQLite that a function may call
+** The SQLITE_SUBTYPE flag indicates to SQLite that a function might call
 ** [sqlite3_value_subtype()] to inspect the sub-types of its arguments.
-** Every function that invokes [sqlite3_value_subtype()] should have this
-** property.  If it does not, then the query planner might generate
-** incorrect code for queries that use that function.
+** This flag instructs SQLite to omit some corner-case optimizations that
+** might disrupt the operation of the [sqlite3_value_subtype()] function,
+** causing it to return zero rather than the correct subtype().
+** SQL functions that invokes [sqlite3_value_subtype()] should have this
+** property.  If the SQLITE_SUBTYPE property is omitted, then the return
+** value from [sqlite3_value_subtype()] might sometimes be zero even though
+** a non-zero subtype was specified by the function argument expression.
 **
 ** [[SQLITE_RESULT_SUBTYPE]] <dt>SQLITE_RESULT_SUBTYPE</dt><dd>
 ** The SQLITE_RESULT_SUBTYPE flag indicates to SQLite that a function might call
@@ -5796,11 +5800,10 @@ int sqlite3_value_encoding(sqlite3_value*);
 ** routine to set the subtype for the return value of an SQL function.
 **
 ** Every [application-defined SQL function] that invoke this interface
-** <i>must</i> include the [SQLITE_SUBTYPE] property in the text
+** should include the [SQLITE_SUBTYPE] property in the text
 ** encoding argument when the function is [sqlite3_create_function|registered].
-** The sqlite3_value_subtype() can return an incorrect answer if it
-** is invoked from within an application-defined SQL function that does
-** not have the [SQLITE_SUBTYPE] property.
+** If the [SQLITE_SUBTYPE] property is omitted, then sqlite3_value_subtype()
+** might return zero instead of the upstream subtype in some corner cases.
 */
 unsigned int sqlite3_value_subtype(sqlite3_value*);
 
@@ -6222,12 +6225,12 @@ int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
 ** in future releases of SQLite.
 **
 ** Every [application-defined SQL function] that invokes this interface
-** <i>must</i> include the [SQLITE_RESULT_SUBTYPE] property in its
+** should include the [SQLITE_RESULT_SUBTYPE] property in its
 ** text encoding argument when the SQL function is
-** [sqlite3_create_function|registered].  If the sqlite3_result_subtype()
-** interface is invoked within an SQL function that does not have the
-** SQLITE_RESULT_SUBTYPE property, then sqlite3_result_subtype()
-** might fail to set the result subtype.
+** [sqlite3_create_function|registered].  If the [SQLITE_RESULT_SUBTYPE]
+** property is omitted from the function that invokes sqlite3_result_subtype(),
+** then in some cases the sqlite3_result_subtype() might fail to set
+** the result subtype.
 **
 ** If SQLite is compiled with -DSQLITE_STRICT_SUBTYPE=1, then any
 ** SQL function that invokes the sqlite3_result_subtype() interface