Improve README and javadoc.

Author: John-He-928

README.md

@@ -128,7 +128,8 @@ method.
 ### Build WCDB Android with Prebuilt Dependencies
 
 WCDB itself can be built apart from its dependencies using Gradle or Android Studio. 
-To build WCDB Android library, run Gradle on `android` directory:
+To build WCDB Android library, import Gradle project or run Gradle wrapper on 
+`android` directory:
 
 ```bash
 $ cd android
@@ -144,7 +145,9 @@ sdk.dir=path/to/sdk
 ndk.dir=path/to/ndk
 ```
 
-Android Studio will do this for you when the project is imported.
+Android Studio will do this for you when the project is imported. If you have 
+*"Failed to notify project evaluation listener"* error, double check your `ndk.dir`
+property.
 
 ### Build Dependencies from Sources
 

android/wcdb/src/com/tencent/wcdb/database/SQLiteDatabase.java

@@ -2373,7 +2373,20 @@ public boolean isDatabaseIntegrityOk() {
         return true;
     }
 
-
+    /**
+     * Acquire database connection from connection pool and return its native handle
+     * (a.k.a {@code sqlite3 *}).
+     *
+     * <p>The caller must release the returned handle when finished with it by calling
+     * {@link #releaseNativeConnection(long, Exception)} <strong>within the same thread</strong>.
+     * Failed to release the returned handle will cause connection leakage and probably
+     * ANR.</p>
+     *
+     * @param operation     string describing usage of the connection, for logging
+     * @param readOnly      whether operations on returned connection is read-only
+     * @param interactive   whether operations on returned connection is for interactive
+     * @return {@code sqlite3 *} handle casted to {@code long}
+     */
     public long acquireNativeConnectionHandle(String operation, boolean readOnly, boolean interactive) {
         if (operation == null)
             operation = "unnamedNative";
@@ -2387,6 +2400,13 @@ public long acquireNativeConnectionHandle(String operation, boolean readOnly, bo
                 .getNativeHandle(operation);
     }
 
+    /**
+     * Release connection returned by {@link #acquireNativeConnectionHandle(String, boolean, boolean)}.
+     *
+     * @param nativePtr {@code sqlite3 *} handle to release
+     * @param ex        exception occurred during operations on the native handle,
+     *                  or null for successful operations
+     */
     public void releaseNativeConnection(long nativePtr, Exception ex) {
         getThreadSession().releaseConnectionForNativeHandle(ex);
     }
@@ -2429,100 +2449,4 @@ SQLiteProgram newQuery(SQLiteDatabase db, String query,
     public interface CustomFunction {
         public void callback(String[] args);
     }
-
-    public static boolean copyTables(SQLiteDatabase OrgDb, SQLiteDatabase CipDb) {
-        boolean status = false;
-
-        HashSet<String> sysTables = new HashSet<String>();
-        //sysTables.add("android_metadata");
-        sysTables.add("sqlite_sequence");
-
-        StringBuilder sql = new StringBuilder("select DISTINCT  tbl_name from sqlite_master");
-        Cursor cursorTableName = OrgDb.rawQuery(sql.toString(), null);
-        if (cursorTableName != null) {
-            int tblCount = cursorTableName.getCount();
-            while (cursorTableName.moveToNext()) {
-                tblCount--;
-                String tableName = cursorTableName.getString(0);
-
-                sql.setLength(0);
-                sql.append("select sql from sqlite_master where tbl_name = '").append(tableName).append("'");
-                android.database.Cursor cursorTableDesc = OrgDb.rawQuery(sql.toString(), null);
-                if (cursorTableDesc != null) {
-                    if (cursorTableDesc.moveToNext()) {
-                        if (sysTables.contains(tableName)) {
-                            cursorTableDesc.close();
-                            continue;
-                        }
-                        CipDb.execSQL(cursorTableDesc.getString(0));
-
-                        Cursor cursorTableText = OrgDb.rawQuery("select * from " + tableName, null);
-                        if (cursorTableText != null && cursorTableText.getCount() > 0) {
-                            sql.setLength(0);
-                            sql.append("insert into ").append(tableName).append("(");
-                            if (cursorTableText.getColumnCount() > 0) {
-                                StringBuilder value = new StringBuilder(" values(");
-                                for (String columnName : cursorTableText.getColumnNames()) {
-                                    sql.append(columnName).append(",");
-                                    value.append("?,");
-                                }
-                                value.deleteCharAt(value.length() - 1);
-                                sql.deleteCharAt(sql.length() - 1);
-                                sql.append(")").append(value).append(")");
-                            }
-
-                            SQLiteStatement stat = CipDb.compileStatement(sql.toString());
-                            CipDb.beginTransaction();
-
-                            int columnCount = cursorTableText.getColumnCount();
-                            int[] columnTypes = new int[columnCount];
-                            cursorTableText.moveToFirst();
-                            for (int i = 0; i < columnCount; i++)
-                                columnTypes[i] = cursorTableText.getType(i);
-                            do {
-                                for (int i = 0; i < columnCount; i++) {
-                                    switch (columnTypes[i]) {
-                                        case Cursor.FIELD_TYPE_STRING: {
-                                            String s = cursorTableText.getString(i);
-                                            if (s != null) stat.bindString(i + 1, s);
-                                            else stat.bindNull(i + 1);
-                                            break;
-                                        }
-                                        case Cursor.FIELD_TYPE_INTEGER: {
-                                            stat.bindLong(i + 1, cursorTableText.getLong(i));
-                                            break;
-                                        }
-                                        case Cursor.FIELD_TYPE_BLOB: {
-                                            byte[] b = cursorTableText.getBlob(i);
-                                            if (b != null) stat.bindBlob(i + 1, b);
-                                            else stat.bindNull(i + 1);
-                                            break;
-                                        }
-                                        case Cursor.FIELD_TYPE_FLOAT: {
-                                            stat.bindDouble(i + 1, cursorTableText.getDouble(i));
-                                            break;
-                                        }
-                                        case Cursor.FIELD_TYPE_NULL: {
-                                            stat.bindNull(i + 1);
-                                            break;
-                                        }
-                                        default: {
-                                        }
-                                    }
-                                }
-                                stat.executeInsert();
-                            } while (cursorTableText.moveToNext());
-                            CipDb.setTransactionSuccessful();
-                            CipDb.endTransaction();
-                            cursorTableText.close();
-                        }
-                    }
-                    cursorTableDesc.close();
-                }
-            }
-            cursorTableName.close();
-            if (tblCount == 0) status = true;
-        }
-        return status;
-    }
 }

android/wcdb/src/com/tencent/wcdb/database/SQLiteDirectCursor.java

@@ -46,7 +46,16 @@ public class SQLiteDirectCursor extends AbstractCursor {
     private int mCount;
     private boolean mCountFinished;
 
-
+    /**
+     * Execute a query and provide access to its result set through a Cursor
+     * interface. For a query such as: {@code SELECT name, birth, phone FROM
+     * myTable WHERE ... LIMIT 1,20 ORDER BY...} the column names (name, birth,
+     * phone) would be in the projection argument and everything from
+     * {@code FROM} onward would be in the params argument.
+     *
+     * @param editTable the name of the table used for this query
+     * @param query the {@link SQLiteDirectQuery} object associated with this cursor object.
+     */
     public SQLiteDirectCursor(SQLiteCursorDriver driver, String editTable, SQLiteDirectQuery query) {
         if (query == null) {
             throw new IllegalArgumentException("query object cannot be null");

android/wcdb/src/com/tencent/wcdb/database/SQLiteMisuseException.java

@@ -19,14 +19,17 @@
 /**
  * This error can occur if the application creates a SQLiteStatement object and allows multiple
  * threads in the application use it at the same time.
- * Sqlite returns this error if bind and execute methods on this object occur at the same time
- * from multiple threads, like so:
- *     thread # 1: in execute() method of the SQLiteStatement object
- *     while thread # 2: is in bind..() on the same object.
+ * <p>
+ * SQLite returns this error if bind and execute methods on this object occur at the same time
+ * from multiple threads, like so:<br>
+ *     thread # 1: in {@code execute()} method of the {@link SQLiteStatement} object<br>
+ *     while thread # 2: is in bind..() on the same object.<br>
  *</p>
- * FIX this by NEVER sharing the same SQLiteStatement object between threads.
+ * <p>
+ * FIX this by NEVER sharing the same {@link SQLiteStatement} object between threads.
  * Create a local instance of the SQLiteStatement whenever it is needed, use it and close it ASAP.
  * NEVER make it globally available.
+ * </p>
  */
 @SuppressWarnings("serial")
 public class SQLiteMisuseException extends SQLiteException {