javadoc additions.

FossilOrigin-Name: bedf33d403677d243a1505ce549166850ab55671700b143278db5feb84883ab3

ext/jni/src/org/sqlite/jni/Authorizer.java

@@ -18,12 +18,8 @@ package org.sqlite.jni;
 */
 public interface Authorizer {
   /**
-     Must functions as described for the sqlite3_set_authorizer()
-     callback, with one caveat: the string values passed here were
-     initially (at the C level) encoded in standard UTF-8. If they
-     contained any constructs which are not compatible with MUTF-8,
-     these strings will not have the expected values. For further
-     details, see the documentation for the SQLite3Jni class.
+     Must function as described for the sqlite3_set_authorizer()
+     callback.
 
      Must not throw.
   */

ext/jni/src/org/sqlite/jni/NativePointerHolder.java

@@ -23,7 +23,7 @@ package org.sqlite.jni;
    NativePointerHolder is not inadvertently passed to an incompatible
    function signature.
 
-   These objects do not _own_ the pointer they refer to.  They are
+   These objects do not own the pointer they refer to.  They are
    intended simply to communicate that pointer between C and Java.
 */
 public class NativePointerHolder<ContextType> {

ext/jni/src/org/sqlite/jni/NotNull.java

@@ -0,0 +1,21 @@
+package org.sqlite.jni;
+
+/**
+   This annotation is for flagging parameters which may not legally be
+   null. Note that the C-style API does not throw any
+   NullPointerExceptions on its own because it has a no-throw policy
+   in order to retain its C-style semantics.
+
+   <p>This annotation is informational only. No policy is in place to
+   programmatically ensure that NotNull is conformed to in client
+   code.
+
+   <p>This annotation is solely for the use by the classes in this
+   package but is made public so that javadoc will link to it from the
+   annotated functions. It is not part of the public API and
+   client-level code must not rely on it.
+*/
+@java.lang.annotation.Documented
+@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE)
+@java.lang.annotation.Target(java.lang.annotation.ElementType.PARAMETER)
+public @interface NotNull{}

ext/jni/src/org/sqlite/jni/Nullable.java

@@ -0,0 +1,16 @@
+package org.sqlite.jni;
+
+/**
+   This annotation is for flagging parameters which may legally be
+   null, noting that they may behave differently if passed null but
+   are prepared to expect null as a value.
+
+   <p>This annotation is solely for the use by the classes in this
+   package but is made public so that javadoc will link to it from the
+   annotated functions. It is not part of the public API and
+   client-level code must not rely on it.
+*/
+@java.lang.annotation.Documented
+@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE)
+@java.lang.annotation.Target(java.lang.annotation.ElementType.PARAMETER)
+public @interface Nullable{}

ext/jni/src/org/sqlite/jni/OutputPointer.java

@@ -16,13 +16,13 @@ package org.sqlite.jni;
 /**
    Helper classes for handling JNI output pointers.
 
-   We do not use a generic OutputPointer<T> because working with those
+   <p>We do not use a generic OutputPointer<T> because working with those
    from the native JNI code is unduly quirky due to a lack of
    autoboxing at that level.
 
-   The usage is similar for all of thes types:
+   <p>The usage is similar for all of thes types:
 
-   ```
+   <pre>{@code
    OutputPointer.sqlite3 out = new OutputPointer.sqlite3();
    assert( null==out.get() );
    int rc = sqlite3_open(":memory:", out);
@@ -30,14 +30,14 @@ package org.sqlite.jni;
    assert( null!=out.get() );
    sqlite3 db = out.take();
    assert( null==out.get() );
-   ```
+   }</pre>
 
-   With the minor exception that the primitive types permit direct
+   <p>With the minor exception that the primitive types permit direct
    access to the object's value via the `value` property, whereas the
    JNI-level opaque types do not permit client-level code to set that
    property.
 
-   Warning: do not share instances of these classes across
+   <p>Warning: do not share instances of these classes across
    threads. Doing so may lead to corrupting sqlite3-internal state.
 */
 public final class OutputPointer {

ext/jni/src/org/sqlite/jni/SQLite3Jni.java

@@ -19,49 +19,22 @@ import java.lang.annotation.Target;
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 
-/**
-   This annotation is for flagging parameters which may legally be
-   null, noting that they may behave differently if passed null but
-   are prepared to expect null as a value.
-
-   This annotation is solely for the reader's information.
-*/
-@Documented
-@Retention(RetentionPolicy.SOURCE)
-@Target(ElementType.PARAMETER)
-@interface Nullable{}
-
-/**
-   This annotation is for flagging parameters which may not legally be
-   null. Note that the C-style API does not throw any
-   NullPointerExceptions on its own because it has a no-throw policy
-   in order to retain its C-style semantics.
-
-   This annotation is solely for the reader's information. No policy
-   is in place to programmatically ensure that NotNull is conformed to
-   in client code.
-*/
-@Documented
-@Retention(RetentionPolicy.SOURCE)
-@Target(ElementType.PARAMETER)
-@interface NotNull{}
-
 /**
   This class contains the entire sqlite3 JNI API binding.  For
   client-side use, a static import is recommended:
 
-  {@code
+  <pre>{@code
   import static org.sqlite.jni.SQLite3Jni.*;
-  }
+  }</pre>
 
-  The C-side part can be found in sqlite3-jni.c.
+  <p>The C-side part can be found in sqlite3-jni.c.
 
 
   <p>Only functions which materially differ from their C counterparts
-  are documented here. The C documetation is otherwise applicable
-  here:
+  are documented here. The C documentation is otherwise applicable
+  for these APIs:
 
-  <p>{link https://sqlite.org/c3ref/intro.html}
+  <p><a href="https://sqlite.org/c3ref/intro.html">https://sqlite.org/c3ref/intro.html</a>
 
   <p>A handful of Java-specific APIs have been added.
 
@@ -73,31 +46,22 @@ import java.lang.annotation.ElementType;
   but JNI uses what its docs call modified UTF-8 (see links below)
   Care must be taken when converting Java strings to or from standard
   UTF-8 to ensure that the proper conversion is performed. In short,
-  Java's `String.getBytes(StandardCharsets.UTF_8)` performs the proper
+  Java's {@code String.getBytes(StandardCharsets.UTF_8)} performs the proper
   conversion in Java, and there are no JNI C APIs for that conversion
-  (JNI's `NewStringUTF()` requires its input to be in MUTF-8).
+  (JNI's {@code NewStringUTF()} requires its input to be in MUTF-8).
 
   <p>The known consequences and limitations this discrepancy places on
   the SQLite3 JNI binding include:
 
   <ul>
 
-  <li>Any functions which return state from a database take extra care
-  to perform proper conversion, at the cost of efficiency.</li>
-
   <li>C functions which take C-style strings without a length argument
   require special care when taking input from Java. In particular,
   Java strings converted to byte arrays for encoding purposes are not
-  NUL-terminated, and conversion to a Java byte array must be careful
-  to add one. Functions which take a length do not require this so
-  long as the length is provided. Search the SQLite3Jni class for "\0"
-  for many examples.
-
-  <li>Similarly, C-side code which deals with strings which might not
-  be NUL-terminated (e.g. while tokenizing in FTS5-related code)
-  cannot use JNI's new-string functions to return them to Java because
-  none of those APIs take a string-length argument. Such cases must
-  return byte arrays instead of strings.
+  NUL-terminated, and conversion to a Java byte array must sometimes
+  be careful to add one. Functions which take a length do not require
+  this so long as the length is provided. Search the SQLite3Jni class
+  for "\0" for many examples.
 
   </ul>
 
@@ -996,8 +960,9 @@ public final class SQLite3Jni {
 
   /**
      Binds the SQL result to the given object, or
-     sqlite3_result_null() if o is null. Use
-     sqlite3_value_java_object() or sqlite3_column_java_object() to
+     {@link #sqlite3_result_null(sqlite3_context) sqlite3_result_null()} if {@code o} is null. Use
+     {@link #sqlite3_value_java_object(sqlite3_value) sqlite3_value_java_object()} or
+     {@link #sqlite3_column_java_object(sqlite3_stmt,int) sqlite3_column_java_object()} to
      fetch it.
 
      This is implemented in terms of sqlite3_result_pointer(), but
@@ -1093,11 +1058,11 @@ public final class SQLite3Jni {
   /**
      Binds the given text using C's sqlite3_result_blob64() unless:
 
-     - blob is null ==> sqlite3_result_null()
+     - @param blob is null ==> sqlite3_result_null()
 
-     - blob is too large ==> sqlite3_result_error_toobig()
+     - @param blob is too large ==> sqlite3_result_error_toobig()
 
-     If maxLen is larger than blob.length, it is truncated to that
+     If @param maxLen is larger than blob.length, it is truncated to that
      value. If it is negative, results are undefined.
   */
   private static native void sqlite3_result_blob64(
@@ -1138,7 +1103,7 @@ public final class SQLite3Jni {
      - text is too large: translates to a call to
        sqlite3_result_error_toobig()
 
-     - The `encoding` argument has an invalid value: translates to
+       - The @param encoding argument has an invalid value: translates to
        sqlite3_result_error_code() with code SQLITE_FORMAT.
 
      If maxLength (in bytes, not characters) is larger than

ext/jni/src/org/sqlite/jni/package-info.java

@@ -2,5 +2,7 @@
    This package houses a JNI binding to the SQLite3 C API.
 
    The docs are in progress.
+
+   The primary interfaces are in {@link org.sqlite.jni.SQLite3Jni}.
 */
 package org.sqlite.jni;

ext/jni/src/org/sqlite/jni/sqlite3_context.java

@@ -47,9 +47,9 @@ public final class sqlite3_context extends NativePointerHolder<sqlite3_context>
 
      <p>Consider this SQL, where MYFUNC is a user-defined aggregate function:
 
-     {code
+     <pre>{@code
      SELECT MYFUNC(A), MYFUNC(B) FROM T;
-     }
+     }</pre>
 
      <p>The xStep() and xFinal() methods of the callback need to be able
      to differentiate between those two invocations in order to