Basic JavaDoc

Change-Id: I75cd769dd3f9cd4c6d6cc1de13d411646827430c

Author: samtstern

firestore/src/main/java/com/firebase/ui/firestore/FirestoreInfiniteScrollListener.java

@@ -5,7 +5,8 @@
 import android.support.v7.widget.RecyclerView;
 
 /**
- * TODO(samstern): Document
+ * RecyclerView scroll listener that triggers loading/unloading in a
+ * {@link FirestorePagingAdapter} so that the adapter can appear to be infinite sroll.
  */
 public class FirestoreInfiniteScrollListener extends RecyclerView.OnScrollListener {
 
@@ -53,7 +54,7 @@ public void run() {
                 @Override
                 public void run() {
                     // Load one page up
-                    mAdapter.loadPrevPage();
+                    mAdapter.loadPageUp();
                 }
             });
         }

firestore/src/main/java/com/firebase/ui/firestore/FirestorePagingAdapter.java

@@ -2,6 +2,7 @@
 
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
+import android.support.annotation.RestrictTo;
 import android.support.v7.widget.RecyclerView;
 import android.util.Log;
 import android.view.ViewGroup;
@@ -17,6 +18,9 @@
 
 /**
  * Adapter to paginate a Cloud Firestore query and bind it to a RecyclerView.
+ *
+ * See also {@link FirestorePagingOptions}.
+ * See also {@link FirestoreInfiniteScrollListener}.
  */
 public abstract class FirestorePagingAdapter<T, VH extends RecyclerView.ViewHolder>
         extends RecyclerView.Adapter<VH> {
@@ -29,6 +33,9 @@ public abstract class FirestorePagingAdapter<T, VH extends RecyclerView.ViewHold
 
     private List<Page> mPages = new ArrayList<>();
 
+    /**
+     * Create a new paging adapter from the given options.
+     */
     public FirestorePagingAdapter(FirestorePagingOptions<T> options) {
         mOptions = options;
 
@@ -59,6 +66,11 @@ public void onBindViewHolder(VH holder, int position) {
         onBindViewHolder(holder, position, get(position));
     }
 
+    /**
+     * Get the number of pages currently loaded in memory. This is <b>not</b> the same
+     * as the number of pages ever loaded by the adapter as the adapter dynamically unloads
+     * pages that are not used.
+     */
     public int getPagesLoaded() {
         int count = 0;
         for (Page page : mPages) {
@@ -70,7 +82,13 @@ public int getPagesLoaded() {
         return count;
     }
 
-    public void loadPrevPage() {
+    /**
+     * When scrolling up through the list, load the next not-yet-loaded page.
+     *
+     * If this page load results in the number of loaded pages exceeding the maximum
+     * specified in the options, unload the bottom-most page.
+     */
+    public void loadPageUp() {
         if (countState(PageState.LOADING) > 0) {
             return;
         }
@@ -95,6 +113,12 @@ public void loadPrevPage() {
         }
     }
 
+    /**
+     * When scrolling down through the list, load the next not-yet-loaded page.
+     *
+     * If this page load results in the number of loaded pages exceeding the maximum
+     * specified in the options, unload the top-most page.
+     */
     public void loadNextPage() {
         if (countState(PageState.LOADING) > 0) {
             return;
@@ -144,6 +168,11 @@ public void loadNextPage() {
         }
     }
 
+    /**
+     * Get the total number of loaded items among all loaded pages.
+     *
+     * Note that this operation is O(n) in the number of pages.
+     */
     @Override
     public int getItemCount() {
         int size = 0;
@@ -155,6 +184,12 @@ public int getItemCount() {
         return size;
     }
 
+    /**
+     * Get the snapshot at the specified index, where 0 is the first loaded snapshot. These
+     * indexes are relative to the snapshots loaded at any given time and are not absolute.
+     *
+     * This operation is O(n) in the number of pages.
+     */
     @NonNull
     public DocumentSnapshot getSnapshot(int index) {
         int remaining = index;
@@ -170,11 +205,22 @@ public DocumentSnapshot getSnapshot(int index) {
                 "Requested non-existent index: " + index + ", size=" + getItemCount());
     }
 
+    /**
+     * Get the model at the specified index by converting a snapfrot from
+     * {@link #getSnapshot(int)}.
+     */
     @NonNull
     public T get(int index) {
         return mParser.parseSnapshot(getSnapshot(index));
     }
 
+    /**
+     * Called when a page begins or finishes loading, to indicate if there are any current loading
+     * operations going on.
+     *
+     * Useful to override and control UI elements such as a progress bar or loading spinner.
+     * @param isLoading
+     */
     // TODO: Better interface
     protected void onLoadingStateChanged(boolean isLoading) {
         // No-op, this is for overriding.
@@ -310,12 +356,14 @@ private void logd(String message) {
         }
     }
 
+    @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
     private enum PageState {
         LOADING,
         LOADED,
         UNLOADED
     }
 
+    @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
     private class Page implements OnCompleteListener<QuerySnapshot> {
 
         private final int mIndex;

firestore/src/main/java/com/firebase/ui/firestore/FirestorePagingOptions.java

@@ -6,7 +6,7 @@
  * Options to configure a {@link FirestorePagingAdapter}
  * and {@link FirestoreInfiniteScrollListener}.
  *
- * TODO(samstern): Document all methods.
+ * See {@link Builder} to create a new instance.
  */
 public class FirestorePagingOptions<T> {
 
@@ -30,22 +30,37 @@ public class FirestorePagingOptions<T> {
         mMaxPages = maxPages;
     }
 
+    /**
+     * Get the base query to be used for paging.
+     */
     public Query getQuery() {
         return mQuery;
     }
 
+    /**
+     * Get the {@link SnapshotParser} to be used to parse Firestore document snapshots.
+     */
     public SnapshotParser<T> getParser() {
         return mParser;
     }
 
+    /**
+     * Get the distance from the top/bottom of the list that will trigger a new page load.
+     */
     public int getLoadTriggerDistance() {
         return mLoadTriggerDistance;
     }
 
+    /**
+     * Get the max number of pages to keep in memory at any time.
+     */
     public int getMaxPages() {
         return mMaxPages;
     }
 
+    /**
+     * Get the maximum number of items to load as a single page.
+     */
     public int getPageSize() {
         return mPageSize;
     }
@@ -61,29 +76,54 @@ public static class Builder<T> {
 
         public Builder() {}
 
+        /**
+         * Set the <b>base</b> query for pagination. The query may contain where() and orderBy()
+         * clauses but may not contain any startAt/endAt or limit clauses as those will be
+         * added automatically by the paging adapter.
+         *
+         * @param query the base query.
+         * @param parser the SnapshotParser to be used to parse document snapshots.
+         */
         public Builder<T> setQuery(Query query, SnapshotParser<T> parser) {
             mQuery = query;
             mParser = parser;
             return this;
         }
 
+        /**
+         * Sets the query using a standard {@link ClassSnapshotParser}.
+         *
+         * See {@link #setQuery(Query, Class)} for details.
+         */
         public Builder<T> setQuery(Query query, Class<T> clazz) {
             mQuery = query;
             mParser = new ClassSnapshotParser<>(clazz);
             return this;
         }
 
-
+        /**
+         * Set the maximum number of items to load in a single page.
+         */
         public Builder<T> setPageSize(int pageSize) {
             mPageSize = pageSize;
             return this;
         }
 
+        /**
+         * Set the distance (in items) from the bottom or top of the data set that will trigger
+         * the adapter to load the next page.
+         *
+         * This option is ignored unless a {@link FirestoreInfiniteScrollListener} is
+         * attached to the adapter.
+         */
         public Builder<T> setLoadTriggerDistance(int distance) {
             mLoadTriggerDistance = distance;
             return this;
         }
 
+        /**
+         * Set the maximum number of pages to keep in memory at a time.
+         */
         public Builder<T> setMaxPages(int maxPages) {
             mMaxPages = maxPages;
             return this;