added javadocs

Author: sammefford

src/main/java/com/marklogic/client/Page.java

@@ -17,17 +17,66 @@
 
 import java.util.Iterator;
 
+/** A generic interface for pagination through large sets of items of type <T>. */
 public interface Page<T> extends Iterable<T> {
+    /** An iterator over the items in this page. */
     public Iterator<T> iterator();
+
+    /** The start position of this page within all possible items.  For result sets
+     * this is the position of the first result within the result set.
+     * @return the start position
+     */
     public long getStart();
+
+    /** The page size which is the maximum number of items allowed in one page.
+     * @return the page size */
     public long getPageSize();
+
+    /** The total count (potentially an estimate) of all possible items in the set.
+     *  For result sets this is the number of items within the result set.
+     *  For search result sets this is the estimated number of matching items.
+     * @return the total count of possible items */
     public long getTotalSize();
+
+    /** The count of items in this page, which is always less than getPageSize().  
+     * If ({@link #getTotalSize()} - {@link #getStart()}) &gt; {@link #getPageSize()}
+     * then size() == getPageSize().
+     * @return the count of items in this page
+     */
     public long size();
+
+
+    /** The number of pages covering all possible items. 
+     * @return the number of pages.  Literally, 
+     * <pre>{@code (long) Math.ceil((double) getTotalSize() / (double) getPageSize()); }</pre>
+     */
     public long getTotalPages();
+
+    /** Whether there are any items in this page.  
+     * @return true if {@code size() > 0; }
+     */
     public boolean hasContent();
+
+    /** Whether there are any items in the next page.  
+     * @return true if {@code getPageNumber() < getTotalPages(); }
+     */
     public boolean hasNextPage();
+
+    /** Whether there is a previous page.  
+     * @return true if {@code getPageNumber() > 0 }
+     */
     public boolean hasPreviousPage();
+
+    /** The page number within the count of all possible pages.  
+     * @return {@code (long) Math.floor((double) start / (double) getPageSize()) + 1; }
+     */
     public long getPageNumber();
+
+    /** @return true if {@code getPageNumber() == 1 }
+     */
     public boolean isFirstPage();
+
+    /** @return true if {@code getPageNumber() == getTotalPages() }
+     */
     public boolean isLastPage();
 }