[Java] Improve the Java Doc of RocksObject

Summary:
Improve the Java Doc of RocksObject, which explains more about the life-cycle
of a native handle.

Test Plan: no code change

Reviewers: haobo, sdong, ankgup87

Reviewed By: ankgup87

Subscribers: leveldb

Differential Revision: https://reviews.facebook.net/D19179

java/org/rocksdb/RocksObject.java

@@ -6,12 +6,17 @@
 package org.rocksdb;
 
 /**
- * RocksObject is the base-class of all RocksDB related class that has
+ * RocksObject is the base-class of all RocksDB classes that has a pointer to
- * a pointer to some c++ rocksdb object.  Although RocksObject
+ * some c++ rocksdb object.
- * will release its c++ resource on its finalize() once it has been
+ *
- * garbage-collected, it is suggested to call dispose() manually to
+ * RocksObject has dispose() function, which releases its associated c++ resource.
- * release its c++ resource once an instance of RocksObject is no
+ * This function can be either called manually, or being called automatically
- * longer used.
+ * during the regular Java GC process.  However, since Java may wrongly assume a
+ * RocksObject only contains a long member variable and think it is small in size,
+ * Java may give RocksObject low priority in the GC process.  For this, it is
+ * suggested to call dispose() manually.  However, it is safe to let RocksObject go
+ * out-of-scope without manually calling dispose() as dispose() will be called
+ * in the finalizer during the regular GC process.
  */
 public abstract class RocksObject {
   protected RocksObject() {
@@ -20,7 +25,14 @@ public abstract class RocksObject {
   }
 
   /**
-   * Release the c++ object pointed by the native handle.
+   * Release the c++ object manually pointed by the native handle.
+   *
+   * Note that dispose() will also be called during the GC process
+   * if it was not called before its RocksObject went out-of-scope.
+   * However, since Java may wrongly wrongly assume those objects are
+   * small in that they seems to only hold a long variable. As a result,
+   * they might have low priority in the GC process.  To prevent this,
+   * it is suggested to call dispose() manually.
    *
    * Note that once an instance of RocksObject has been disposed,
    * calling its function will lead undefined behavior.
@@ -47,26 +59,59 @@ public abstract class RocksObject {
    * takes over ownership of the native object or both will attempt to delete
    * the underlying object when garbage collected.
    *
-   * When disOwnNativeHandle is called, dispose() will simply set nativeHandle_
+   * When disOwnNativeHandle() is called, dispose() will simply set nativeHandle_
    * to 0 without releasing its associated C++ resource.  As a result,
-   * incorrectly use this function may cause memory leak.
+   * incorrectly use this function may cause memory leak, and this function call
+   * will not affect the return value of isInitialized().
+   *
+   * @see dispose()
+   * @see isInitialized()
    */
   protected void disOwnNativeHandle() {
     owningHandle_ = false;
   }
 
+  /**
+   * Returns true if the current RocksObject is responsable to release its
+   * native handle.
+   *
+   * @return true if the current RocksObject is responsible to release its
+   *   native handle.
+   *
+   * @see disOwnNativeHandle()
+   * @see dispose()
+   */
   protected boolean isOwningNativeHandle() {
     return owningHandle_;
   }
 
+  /**
+   * Returns true if the associated native handle has been initialized.
+   *
+   * @return true if the associated native handle has been initialized.
+   *
+   * @see dispose()
+   */
   protected boolean isInitialized() {
     return (nativeHandle_ != 0);
   }
 
+  /**
+   * Simply calls dispose() and release its c++ resource if it has not
+   * yet released.
+   */
   @Override protected void finalize() {
     dispose();
   }
 
+  /**
+   * A long variable holding c++ pointer pointing to some RocksDB C++ object.
+   */
   protected long nativeHandle_;
+
+  /**
+   * A flag indicating whether the current RocksObject is responsible to
+   * release the c++ object stored in its nativeHandle_.
+   */
   private boolean owningHandle_;
 }