Merge pull request #509 from cloudant/javadoc-v2-fixes

Fixes to javadoc during v2 review

Author: emlaver

cloudant-sync-datastore-android-encryption/src/main/java/com/cloudant/sync/datastore/encryption/AndroidKeyProvider.java

@@ -23,7 +23,7 @@
 
 /**
  * This class implements the interface {@link KeyProvider} and it can be used to create an
- * encrypted datastore.
+ * encrypted DocumentStore.
  *
  * Given an user-provided password and an identifier, it generates a strong key and store it safely
  * in the application's {@link android.content.SharedPreferences}, so the same key can be retrieved
@@ -32,7 +32,7 @@
  * The password is used to protect the key before saving it to the {@link android.content
  * .SharedPreferences}. The identifier is an
  * easy way to have more than one encryption key in the same app, the only condition is to provide
- * different ids for each of them.
+ * different IDs for each of them.
  *
  * @see KeyProvider
  * @see KeyManager

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/Attachment.java

@@ -89,6 +89,13 @@ public enum Encoding {
         Gzip
     }
 
+    /**
+     * <p>
+     *   Returns the {@link #encoding} encoding using the string in the attachment's JSON metadata.
+     * </p>
+     * @param encodingString the string containing the attachment's {@link #encoding} encoding.
+     * @return the attachment's {@link #encoding} encoding.
+     */
     public static Encoding getEncodingFromString(String encodingString){
         if(encodingString == null || encodingString.isEmpty() || encodingString.equalsIgnoreCase("Plain")){
             return Encoding.Plain;

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/Changes.java

@@ -22,7 +22,7 @@ public interface Changes {
      * <p>This number isn't necessarily the same as the sequence number of the
      * last {@code DocumentRevision} in the list of changes.</p>
      *
-     * @return last sequence number of the changes set
+     * @return last sequence number of the changes set.
      */
     long getLastSequence();
 

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/ConflictResolver.java

@@ -45,7 +45,7 @@ public interface ConflictResolver {
      * @param docId ID of the {@link DocumentRevision} with conflicts
      * @param conflicts list of conflicted {@link DocumentRevision}s, including
      *                  current winner
-     * @return resolved {@link DocumentRevision}
+     * @return the resolved {@link DocumentRevision}.
      *
      * @see Database#resolveConflicts(String, ConflictResolver)
      */

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/Database.java

@@ -34,7 +34,7 @@
  * relational model. The Database exposes a simple key-value model where the key
  * is the document ID combined with a (sometimes optional) revision ID.</p>
  *
- * <p>For a more advanced way of querying the Datastore, see the
+ * <p>For a more advanced way of querying the DocumentStore, see the
  * {@link Query} class</p>
  *
  * <p>Each document consists of a set of revisions, hence most methods within
@@ -91,7 +91,7 @@ DocumentRevision read(String documentId) throws DocumentNotFoundException,
      * <p>Retrieves a given revision of a document.</p>
      *
      * <p>This method gets the revision of a document with a given ID. As the
-     * datastore prunes the content of old revisions to conserve space, this
+     * DocumentStore prunes the content of old revisions to conserve space, this
      * revision may contain the metadata but not content of the revision.</p>
      *
      * <p>Previously deleted documents can be retrieved
@@ -108,35 +108,35 @@ DocumentRevision read(String documentId, String revisionId) throws
             DocumentNotFoundException, DocumentStoreException;
 
     /**
-     * <p>Returns whether this datastore contains a particular revision of
+     * <p>Returns whether this DocumentStore contains a particular revision of
      * a document.</p>
      *
      * <p>{@code true} will still be returned if the document is deleted.</p>
      *
      * @param documentId ID of the document
      * @param revisionId revision of the document
      * @return {@code true} if specified document's particular revision exists
-     *         in the datastore, {@code false} otherwise.
+     *         in the DocumentStore, {@code false} otherwise.
      * @throws DocumentStoreException if there was an error reading from the database
      */
     boolean contains(String documentId, String revisionId) throws DocumentStoreException;
 
     /**
-     * <p>Returns whether this datastore contains any revisions of a document.
+     * <p>Returns whether this DocumentStore contains any revisions of a document.
      * </p>
      *
      * <p>{@code true} will still be returned if the document is deleted.</p>
      *
      * @param documentId ID of the document
      * @return {@code true} if specified document exists
-     *         in the datastore, {@code false} otherwise.
+     *         in the DocumentStore, {@code false} otherwise.
      * @throws DocumentStoreException if there was an error reading from the database
      */
     boolean contains(String documentId) throws DocumentStoreException;
 
     /**
      * <p>Enumerates the current winning revision for all documents in the
-     * datastore.</p>
+     * DocumentStore.</p>
      *
      * <p>Logically, this method takes all the documents sorted by internal ID,
      * in either ascending
@@ -155,7 +155,7 @@ DocumentRevision read(String documentId, String revisionId) throws
 
     /**
      * <p>Enumerates the current winning revision for all documents in the
-     * datastore and return a list of their document IDs.</p>
+     * DocumentStore and return a list of their document IDs.</p>
      *
      * @return list of document IDs
      * @throws DocumentStoreException if there was an error reading from the database
@@ -166,7 +166,7 @@ DocumentRevision read(String documentId, String revisionId) throws
      * <p>Returns the current winning revisions for a set of documents.</p>
      *
      * <p>If the {@code documentIds} list contains document IDs not present
-     * in the datastore, they will be skipped and there will be no entry for
+     * in the DocumentStore, they will be skipped and there will be no entry for
      * them in the returned list.</p>
      *
      * @param documentIds list of document IDs.
@@ -180,7 +180,7 @@ DocumentRevision read(String documentId, String revisionId) throws
      *
      * <p>The sequence number is incremented every time the
      * content of the Database is changed. Each document revision within the
-     * datastore has an associated sequence number, describing when the change
+     * DocumentStore has an associated sequence number, describing when the change
      * took place.</p>
      *
      * <p>The sequence number is particularly useful to find out the changes
@@ -194,9 +194,9 @@ DocumentRevision read(String documentId, String revisionId) throws
     long getLastSequence() throws DocumentStoreException;
 
     /**
-     * <p>Return the number of documents in the datastore</p>
+     * <p>Return the number of documents in the DocumentStore</p>
      *
-     * @return number of non-deleted documents in datastore
+     * @return number of non-deleted documents in DocumentStore
      * @throws DocumentStoreException if there was an error reading from the database.
      */
     int getDocumentCount() throws DocumentStoreException;
@@ -216,15 +216,15 @@ DocumentRevision read(String documentId, String revisionId) throws
     Changes changes(long since, int limit) throws DocumentStoreException;
 
     /**
-     * <p>Return {@code @Iterable<String>} over ids to all the Documents with
+     * <p>Return {@code @Iterable<String>} over IDs to all the Documents with
      * conflicted revisions.</p>
      *
      * <p>Document is modeled as a tree. If a document has at least two leaf
      * revisions that not deleted, those leaf revisions considered
      * conflicted revisions of the document.
      * </p>
      *
-     * @return Iterable of String over ids of all Documents with
+     * @return Iterable of String over IDs of all Documents with
      *         conflicted revisions
      *
      * @see <a target="_blank" href="http://wiki.apache.org/couchdb/Replication_and_conflicts">Replication and conflicts</a>
@@ -234,8 +234,8 @@ DocumentRevision read(String documentId, String revisionId) throws
 
     /**
      * <p>
-     * Resolve conflicts for specified Document using the
-     * given {@code ConflictResolver}
+     * Resolve conflicts for a specified Document using the
+     * given {@code ConflictResolver}.
      * </p>
      *
      * @param docId ID of Document to resolve conflicts
@@ -274,7 +274,7 @@ DocumentRevision create(DocumentRevision rev) throws AttachmentException,
             InvalidDocumentException, ConflictException, DocumentStoreException;
 
     /**
-     * <p>Updates a document that exists in the datastore with with body and attachments
+     * <p>Updates a document that exists in the DocumentStore with with body and attachments
      * from <code>rev</code>.
      * </p>
      *
@@ -296,7 +296,7 @@ DocumentRevision update(DocumentRevision rev) throws ConflictException,
             AttachmentException, DocumentStoreException, DocumentNotFoundException;
 
     /**
-     * <p>Deletes a document from the datastore.</p>
+     * <p>Deletes a document from the DocumentStore.</p>
      *
      * <p>This operation leaves a "tombstone" for the deleted document, so that
      * future replication operations can successfully replicate the deletion.
@@ -347,7 +347,7 @@ DocumentRevision delete(DocumentRevision rev) throws ConflictException, Document
     void compact() throws DocumentStoreException;
 
     /**
-     * <p>Returns the EventBus which this Datastore posts
+     * <p>Returns the EventBus which this DocumentStore posts
      * {@link com.cloudant.sync.event.notifications.DocumentModified Document Notification Events} to.</p>
      * @return the EventBus
      *

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/DocumentRevision.java

@@ -23,12 +23,12 @@
 
 
 /**
- * <p>A single revision of a document within a datastore.</p>
+ * <p>A single revision of a document within a DocumentStore.</p>
  *
- * <p>Documents within the datastore are in fact trees of document revisions,
+ * <p>Documents within the DocumentStore are in fact trees of document revisions,
  * with one document marked as the current winner at any point. Branches in
  * the tree are caused when a document is edited in more than one place before
- * being replicated between datastores. The consuming application is responsible
+ * being replicated between DocumentStores. The consuming application is responsible
  * for finding active branches (also called conflicts), and marking the leaf
  * nodes of all branches but one deleted (thereby resolving the conflict).</p>
  *
@@ -66,7 +66,7 @@ public class DocumentRevision {
     protected DocumentBody body;
 
     public DocumentRevision() {
-        // BasicDatastore#create will assign an ID
+        // DatabaseImpl#create will assign an ID
         this(null);
     }
 
@@ -155,7 +155,7 @@ public boolean isFullRevision(){
      * {@link QueryImpl#find(Map, long, long, List, List)} using the
      * {@code fields} option to limit the fields returned, a revision will be missing data so it
      * cannot be regarded as a full revision. If the document is a full revision, this method will
-     * only attempt to load the full revision from the datastore if {@link InternalDocumentRevision#isFullRevision()}
+     * only attempt to load the full revision from the DocumentStore if {@link InternalDocumentRevision#isFullRevision()}
      * returns false.
      *
      * @return A "Full" document revision.

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/DocumentStore.java

@@ -57,9 +57,10 @@
  * </p>
  *
  * <p>
- * In most cases, users are advised to open store instances and use them for the entire lifetime of
- * their application. This is more efficient than opening and closing instances for the same
- * underlying file system location multiple times throughout the lifetime of the application.
+ * In most cases, users are advised to obtain a single store instance via
+ * {@link DocumentStore#getInstance} and use it for the entire lifetime of their application.
+ * This is more efficient than opening and closing instances for the same underlying file system
+ * location multiple times throughout the lifetime of the application.
  * Users should call {@link #close()} after using a store to shut down in an orderly manner and free
  * up resources.
  * </p>
@@ -74,7 +75,7 @@ public class DocumentStore {
     private final File location; // needed for close/delete
     private final File extensionsLocation; // for extensions: currently attachments and indexes
 
-    /* This map should only be accessed inside synchronized(openDatastores) blocks */
+    /* This map should only be accessed inside synchronized(documentStores) blocks */
     private static final Map<File, DocumentStore> documentStores = new HashMap<File, DocumentStore>();
 
     private static EventBus eventBus = new EventBus();
@@ -215,6 +216,13 @@ public Query query() {
         return query;
     }
 
+    /**
+     * <p>
+     * Closes the DocumentStore instance.
+     * If multiple references are held to the {@link DocumentStore} instance, then this method
+     * should only be called when all objects are finished using the instance.
+     * </p>
+     */
     @SuppressWarnings("unchecked")
     public void close() {
         synchronized (documentStores) {
@@ -230,22 +238,30 @@ public void close() {
         eventBus.post(new DocumentStoreClosed(databaseName));
     }
 
+    /**
+     * <p>
+     * Deletes the DocumentStore instance.
+     * </p>
+     *
+     * @throws DocumentStoreNotDeletedException if the DocumentStore doesn't exist on disk or
+     * if there was an error deleting the DocumentStore directory.
+     */
     public void delete() throws DocumentStoreNotDeletedException {
         try {
             this.close();
         } catch (Exception e) {
-            // caught exception could be something benign like datastore already closed, so just log
+            // caught exception could be something benign like DocumentStore already closed, so just log
             logger.log(Level.WARNING, "Caught exception whilst closing DocumentStore in delete()", e);
         }
         if (!location.exists()) {
-            String msg = String.format("Datastore %s doesn't exist on disk", location);
+            String msg = String.format("DocumentStore %s doesn't exist on disk", location);
             logger.warning(msg);
             throw new DocumentStoreNotDeletedException(msg);
         } else {
             try {
                 FileUtils.deleteDirectory(location);
             } catch (IOException ioe) {
-                String msg = String.format("Datastore %s not deleted", location);
+                String msg = String.format("DocumentStore %s not deleted", location);
                 logger.log(Level.WARNING, msg, ioe);
                 throw new DocumentStoreNotDeletedException(msg, ioe);
             }
@@ -254,7 +270,7 @@ public void delete() throws DocumentStoreNotDeletedException {
     }
 
     /**
-     * <p>Returns the EventBus which this Datastore posts
+     * <p>Returns the EventBus which this DocumentStore posts
      * {@link DocumentStoreModified Database Notification Events} to.</p>
      * @return the DocumentStore's EventBus
      *

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/encryption/CachingKeyProvider.java

@@ -18,10 +18,10 @@
 
 /**
  * Given a user-provided {@link KeyProvider}, it provides an in-memory cache for retrieving an
- * {@link EncryptionKey}. This improves performance when multiple encrypted datastores are used.
+ * {@link EncryptionKey}. This improves performance when multiple encrypted DocumentStores are used.
  *
  * This class implements the interface {@link KeyProvider} and it can be used to create an
- * encrypted datastore.
+ * encrypted DocumentStore.
  *
  * @see KeyProvider
  */
@@ -36,7 +36,7 @@ public class CachingKeyProvider implements KeyProvider {
      * Creates a {@link CachingKeyProvider} containing a {@link KeyProvider} whose {@link
      * EncryptionKey} can be cached
      *
-     * @param keyProvider The {@link KeyProvider} to use for encrypting a datastore
+     * @param keyProvider The {@link KeyProvider} to use for encrypting a DocumentStore
      */
     public CachingKeyProvider(KeyProvider keyProvider) {
         if (keyProvider == null) {

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/encryption/EncryptionKey.java

@@ -18,10 +18,9 @@
 
 /**
  * Class to enforce restrictions on encryption keys used
- * with the datastore.
+ * with the DocumentStore.
  *
- * SQLCipher requires a 32-byte/256-bit key. This class
- * enforces that.
+ * Note: SQLCipher requires a 32-byte/256-bit key.
  */
 public class EncryptionKey {
 

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/encryption/KeyProvider.java

@@ -13,17 +13,14 @@
  */
 
 package com.cloudant.sync.documentstore.encryption;
-
 /**
  * Classes implementing this interface provide encryption
- * keys used by the datastore when encryption is enabled.
- *
- * Created by Mike Rhodes on 11/05/15.
+ * keys used by the DocumentStore when encryption is enabled.
  */
 public interface KeyProvider {
 
     /**
-     * @return the encryption key used to encrypt datastore data
+     * @return the encryption key used to encrypt DocumentStore data
      */
     EncryptionKey getEncryptionKey();
 }

cloudant-sync-datastore-core/src/main/java/com/cloudant/sync/documentstore/encryption/SimpleKeyProvider.java

@@ -18,7 +18,7 @@
 /**
  * SimpleKeyProvider simply takes raw key bytes in its
  * constructor and uses these to provide that key to
- * datastore methods.
+ * DocumentStore methods.
  */
 public class SimpleKeyProvider implements KeyProvider {