OAK-1852 DocumentStore API: improve documentation of keys

git-svn-id: https://svn.apache.org/repos/asf/jackrabbit/oak/trunk@1651594 13f79535-47bb-0310-9956-ffa450edef68

oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/Document.java

@@ -32,14 +32,19 @@
 import com.google.common.collect.Maps;
 
 /**
- * A document corresponds to a node stored in the DocumentMK. A document contains
- * all the revisions of a node stored in the {@link DocumentStore}.
+ * A document corresponds to a node stored in the DocumentNodeStore. A document
+ * contains all the revisions of a node stored in the {@link DocumentStore}.
  */
 public class Document implements CacheValue {
 
     /**
-     * The node id, which contains the depth of the path
-     * (0 for root, 1 for children of the root), and then the path.
+     * The name of the field that contains the document id (the primary key /
+     * the key). The id uniquely identifies a document within a collection. The
+     * requirements and limits of the id are documented in the
+     * {@link DocumentStore} class.
+     * 
+     * For nodes, the document id contains the depth of the path (0 for root, 1
+     * for children of the root), and then the path.
      */
     public static final String ID = "_id";
 
@@ -60,15 +65,19 @@ public class Document implements CacheValue {
     private AtomicBoolean sealed = new AtomicBoolean(false);
 
     /**
-     * @return the id of this document or <code>null</code> if none is set.
+     * Get the id (the primary key) of this document.
+     * 
+     * @return the id or <code>null</code> if none is set.
      */
     @CheckForNull
     public String getId() {
         return (String) get(ID);
     }
 
     /**
-     * @return the modification count of this document or <code>null</code> if
+     * Get the modification count of this document.
+     * 
+     * @return the count or <code>null</code> if
      *         none is set.
      */
     @CheckForNull

oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java

@@ -28,14 +28,17 @@
  * document. That is, an implementation does not have to guarantee atomicity of
  * the entire effect of a method call. A method that fails with an exception may
  * have modified just some documents and then abort. However, an implementation
- * must not modify a document partially. Either the complete update operation
- * is applied to a document or no modification is done at all.
+ * must not modify a document partially. Either the complete update operation is
+ * applied to a document or no modification is done at all.
  * <p>
  * Even though none of the methods declare an exception, they will still throw
  * an implementation specific runtime exception when the operations fails (e.g.
  * an I/O error occurs).
  * <p>
- * For keys, the maximum length is 512 bytes in the UTF-8 representation.
+ * The key is the id of a document. Keys are opaque strings. All characters are
+ * allowed. Leading and trailing whitespace is allowed. For keys, the maximum
+ * length is 512 bytes in the UTF-8 representation (in the latest Unicode
+ * version).
  */
 public interface DocumentStore {