Update documentation generation

Author: developernotes

custom_rules.xml

@@ -17,11 +17,22 @@
 
   <target name="-javadoc" description="Generate Javadocs">
     <property name="javadoc.jar.name" value="${out.dir}/sqlcipher-javadoc.jar" />
-    <javadoc sourcepath="${source.dir}"
+    <javadoc sourcepath="${source.dir};gen"
              destdir="${out.dir}/javadoc"
              packagenames="net.sqlcipher.*"
-             windowtitle="SQLCipher for Android"
-             doctitle="SQLCipher for Android" />
+             bootclasspath="${env.JAVA_HOME}/jre/lib/rt.jar"
+             docletpath="${user.dir}/jars/doclava-1.0.6.jar" >
+      <doclet name="com.google.doclava.Doclava">
+        <param name="-hdf"/>
+        <param name="project.name"/>
+        <param name="SQLCipher for Android"/>
+      </doclet>  
+      <classpath>
+        <fileset dir="${sdk.dir}/platforms/${target}">
+            <include name="android.jar"/>
+        </fileset>
+    </classpath>
+    </javadoc>
     <delete file="${javadoc.jar.name}"/>
     <jar destfile="${javadoc.jar.name}"
          includes="net/sqlcipher/**"
@@ -62,4 +73,4 @@
     <copy file="${out.dir}/sqlcipher-javadoc.jar" todir="${jar.dir}" preservelastmodified="true" overwrite="true"/>
   </target>
 
-</project>
+</project>

jars/doclava-1.0.6.jar

@@ -495,7 +495,7 @@ public static String dumpCurrentRowToString(Cursor cursor) {
      *
      * @param cursor The cursor to read from
      * @param field The TEXT field to read
-     * @param values The {@link ContentValues} to put the value into, with the field as the key
+     * @param values The ContentValues to put the value into, with the field as the key
      */
     public static void cursorStringToContentValues(Cursor cursor, String field,
             ContentValues values) {
@@ -520,7 +520,7 @@ public static void cursorStringToInsertHelper(Cursor cursor, String field,
      *
      * @param cursor The cursor to read from
      * @param field The TEXT field to read
-     * @param values The {@link ContentValues} to put the value into, with the field as the key
+     * @param values The ContentValues to put the value into, with the field as the key
      * @param key The key to store the value with in the map
      */
     public static void cursorStringToContentValues(Cursor cursor, String field,
@@ -533,7 +533,7 @@ public static void cursorStringToContentValues(Cursor cursor, String field,
      *
      * @param cursor The cursor to read from
      * @param field The INTEGER field to read
-     * @param values The {@link ContentValues} to put the value into, with the field as the key
+     * @param values The ContentValues to put the value into, with the field as the key
      */
     public static void cursorIntToContentValues(Cursor cursor, String field, ContentValues values) {
         cursorIntToContentValues(cursor, field, values, field);
@@ -544,7 +544,7 @@ public static void cursorIntToContentValues(Cursor cursor, String field, Content
      *
      * @param cursor The cursor to read from
      * @param field The INTEGER field to read
-     * @param values The {@link ContentValues} to put the value into, with the field as the key
+     * @param values The ContentValues to put the value into, with the field as the key
      * @param key The key to store the value with in the map
      */
     public static void cursorIntToContentValues(Cursor cursor, String field, ContentValues values,
@@ -562,7 +562,7 @@ public static void cursorIntToContentValues(Cursor cursor, String field, Content
      *
      * @param cursor The cursor to read from
      * @param field The INTEGER field to read
-     * @param values The {@link ContentValues} to put the value into, with the field as the key
+     * @param values The ContentValues to put the value into, with the field as the key
      */
     public static void cursorLongToContentValues(Cursor cursor, String field, ContentValues values)
     {
@@ -574,7 +574,7 @@ public static void cursorLongToContentValues(Cursor cursor, String field, Conten
      *
      * @param cursor The cursor to read from
      * @param field The INTEGER field to read
-     * @param values The {@link ContentValues} to put the value into
+     * @param values The ContentValues to put the value into
      * @param key The key to store the value with in the map
      */
     public static void cursorLongToContentValues(Cursor cursor, String field, ContentValues values,
@@ -593,7 +593,7 @@ public static void cursorLongToContentValues(Cursor cursor, String field, Conten
      *
      * @param cursor The cursor to read from
      * @param field The REAL field to read
-     * @param values The {@link ContentValues} to put the value into
+     * @param values The ContentValues to put the value into
      */
     public static void cursorDoubleToCursorValues(Cursor cursor, String field, ContentValues values)
     {
@@ -605,7 +605,7 @@ public static void cursorDoubleToCursorValues(Cursor cursor, String field, Conte
      *
      * @param cursor The cursor to read from
      * @param field The REAL field to read
-     * @param values The {@link ContentValues} to put the value into
+     * @param values The ContentValues to put the value into
      * @param key The key to store the value with in the map
      */
     public static void cursorDoubleToContentValues(Cursor cursor, String field,
@@ -622,7 +622,7 @@ public static void cursorDoubleToContentValues(Cursor cursor, String field,
      * Read the entire contents of a cursor row and store them in a ContentValues.
      *
      * @param cursor the cursor to read from.
-     * @param values the {@link ContentValues} to put the row into.
+     * @param values the ContentValues to put the row into.
      */
     public static void cursorRowToContentValues(Cursor cursor, ContentValues values) {
         AbstractWindowedCursor awc =
@@ -718,7 +718,7 @@ public static String stringForQuery(SQLiteStatement prog, String[] selectionArgs
      *
      * @param cursor The cursor to read from
      * @param column The column to read
-     * @param values The {@link ContentValues} to put the value into
+     * @param values The ContentValues to put the value into
      */
     public static void cursorStringToContentValuesIfPresent(Cursor cursor, ContentValues values,
             String column) {
@@ -734,7 +734,7 @@ public static void cursorStringToContentValuesIfPresent(Cursor cursor, ContentVa
      *
      * @param cursor The cursor to read from
      * @param column The column to read
-     * @param values The {@link ContentValues} to put the value into
+     * @param values The ContentValues to put the value into
      */
     public static void cursorLongToContentValuesIfPresent(Cursor cursor, ContentValues values,
             String column) {
@@ -750,7 +750,7 @@ public static void cursorLongToContentValuesIfPresent(Cursor cursor, ContentValu
      *
      * @param cursor The cursor to read from
      * @param column The column to read
-     * @param values The {@link ContentValues} to put the value into
+     * @param values The ContentValues to put the value into
      */
     public static void cursorShortToContentValuesIfPresent(Cursor cursor, ContentValues values,
             String column) {
@@ -766,7 +766,7 @@ public static void cursorShortToContentValuesIfPresent(Cursor cursor, ContentVal
      *
      * @param cursor The cursor to read from
      * @param column The column to read
-     * @param values The {@link ContentValues} to put the value into
+     * @param values The ContentValues to put the value into
      */
     public static void cursorIntToContentValuesIfPresent(Cursor cursor, ContentValues values,
             String column) {
@@ -782,7 +782,7 @@ public static void cursorIntToContentValuesIfPresent(Cursor cursor, ContentValue
      *
      * @param cursor The cursor to read from
      * @param column The column to read
-     * @param values The {@link ContentValues} to put the value into
+     * @param values The ContentValues to put the value into
      */
     public static void cursorFloatToContentValuesIfPresent(Cursor cursor, ContentValues values,
             String column) {
@@ -798,7 +798,7 @@ public static void cursorFloatToContentValuesIfPresent(Cursor cursor, ContentVal
      *
      * @param cursor The cursor to read from
      * @param column The column to read
-     * @param values The {@link ContentValues} to put the value into
+     * @param values The ContentValues to put the value into
      */
     public static void cursorDoubleToContentValuesIfPresent(Cursor cursor, ContentValues values,
             String column) {

src/net/sqlcipher/DatabaseUtils.java

@@ -55,25 +55,23 @@
 import android.util.Pair;
 
 /**
- * Exposes methods to manage a SQLite database.
+ * Exposes methods to manage a SQLCipher database.
  * <p>SQLiteDatabase has methods to create, delete, execute SQL commands, and
  * perform other common database management tasks.
- * <p>See the Notepad sample application in the SDK for an example of creating
- * and managing a database.
+ * <p>A call to <code>loadLibs(…)</code> should occur before attempting to
+ * create or open a database connection.
  * <p> Database names must be unique within an application, not across all
  * applications.
  *
- * <h3>Localized Collation - ORDER BY</h3>
- * <p>In addition to SQLite's default <code>BINARY</code> collator, Android supplies
- * two more, <code>LOCALIZED</code>, which changes with the system's current locale
- * if you wire it up correctly (XXX a link needed!), and <code>UNICODE</code>, which
- * is the Unicode Collation Algorithm and not tailored to the current locale.
  */
 public class SQLiteDatabase extends SQLiteClosable {
     private static final String TAG = "Database";
     private static final int EVENT_DB_OPERATION = 52000;
     private static final int EVENT_DB_CORRUPT = 75004;
 
+  /**
+   * The version number of the SQLCipher for Android Java client library.
+   */
     public static final String SQLCIPHER_ANDROID_VERSION = "3.4.0";
 
     // Stores reference to all databases opened in the current process.
@@ -165,10 +163,16 @@ private static void loadICUData(Context context, File workingDir) {
       }
     }
 
+  /**
+   * Loads the native SQLCipher library into the application process.
+   */
     public static synchronized void loadLibs (Context context) {
         loadLibs(context, context.getFilesDir());
     }
 
+  /**
+   * Loads the native SQLCipher library into the application process.
+   */
     public static synchronized void loadLibs (Context context, File workingDir) {
       System.loadLibrary("sqlcipher");
 
@@ -1018,16 +1022,14 @@ public static SQLiteDatabase openDatabase(String path, String password, CursorFa
      *            cursor when query is called, or null for default
      * @param flags to control database access mode and other options
      * @param hook to run on pre/post key events (may be null)
-     * @param errorHandler The {@link DatabaseErrorHandler} to be used when sqlite reports database
-     * corruption (or null for default).
      *
      * @return the newly opened database
      *
      * @throws SQLiteException if the database cannot be opened
      * @throws IllegalArgumentException if the database path is null
      */
-    public static SQLiteDatabase openDatabase(String path, char[] password, CursorFactory factory, int flags, SQLiteDatabaseHook databaseHook) {
-        return openDatabase(path, password, factory, flags, databaseHook, new DefaultDatabaseErrorHandler());
+    public static SQLiteDatabase openDatabase(String path, char[] password, CursorFactory factory, int flags, SQLiteDatabaseHook hook) {
+        return openDatabase(path, password, factory, flags, hook, new DefaultDatabaseErrorHandler());
     }
 
     /**

src/net/sqlcipher/database/SQLiteDatabase.java

@@ -1,6 +1,15 @@
 package net.sqlcipher.database;
 
+/**
+ * An interface to perform pre and post key operations against a database.
+ */
 public interface SQLiteDatabaseHook {
+    /**
+     * Called immediately before opening the database.
+     */
     void preKey(SQLiteDatabase database);
+    /**
+     * Called immediately after opening the database.
+     */
     void postKey(SQLiteDatabase database);
 }

src/net/sqlcipher/database/SQLiteDatabaseHook.java

@@ -0,0 +1,4 @@
+/**
+ * Contains the SQLCipher database managements classes that an application would use to manage its own private database.
+ */
+package net.sqlcipher.database;

src/net/sqlcipher/database/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Contains classes to explore data returned from a SQLCipher database.
+ */
+package net.sqlcipher;