JavaDoc for paging adapter (#1298)

Author: samtstern

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

@@ -16,6 +16,8 @@
 
 /**
  * Options to configure an {@link FirestorePagingAdapter}.
+ *
+ * Use {@link Builder} to create a new instance.
  */
 public final class FirestorePagingOptions<T> {
 
@@ -54,27 +56,47 @@ public LifecycleOwner getOwner() {
         return mOwner;
     }
 
+    /**
+     * Builder for {@link FirestorePagingOptions}.
+     */
     public static final class Builder<T> {
 
         private LiveData<PagedList<DocumentSnapshot>> mData;
         private SnapshotParser<T> mParser;
         private LifecycleOwner mOwner;
         private DiffUtil.ItemCallback<DocumentSnapshot> mDiffCallback;
 
+        /**
+         * Sets the query using {@link Source#DEFAULT} and a {@link ClassSnapshotParser} based
+         * on the given Class.
+         *
+         * See {@link #setQuery(Query, Source, PagedList.Config, SnapshotParser)}.
+         */
         @NonNull
         public Builder<T> setQuery(@NonNull Query query,
                                    @NonNull PagedList.Config config,
                                    @NonNull Class<T> modelClass) {
             return setQuery(query, Source.DEFAULT, config, modelClass);
         }
 
+        /**
+         * Sets the query using {@link Source#DEFAULT} and a custom {@link SnapshotParser}.
+         *
+         * See {@link #setQuery(Query, Source, PagedList.Config, SnapshotParser)}.
+         */
         @NonNull
         public Builder<T> setQuery(@NonNull Query query,
                                    @NonNull PagedList.Config config,
                                    @NonNull SnapshotParser<T> parser) {
             return setQuery(query, Source.DEFAULT, config, parser);
         }
 
+        /**
+         * Sets the query using a custom {@link Source} and a {@link ClassSnapshotParser} based
+         * on the given class.
+         *
+         * See {@link #setQuery(Query, Source, PagedList.Config, SnapshotParser)}.
+         */
         @NonNull
         public Builder<T> setQuery(@NonNull Query query,
                                    @NonNull Source source,
@@ -83,6 +105,17 @@ public Builder<T> setQuery(@NonNull Query query,
             return setQuery(query, source, config, new ClassSnapshotParser<>(modelClass));
         }
 
+        /**
+         * Sets the Firestore query to paginate.
+         *
+         * @param query the Firestore query. This query should only contain where() and
+         *              orderBy() clauses. Any limit() or pagination clauses will cause errors.
+         * @param source the data source to use for query data.
+         * @param config paging configuration, passed directly to the support paging library.
+         * @param parser the {@link SnapshotParser} to parse {@link DocumentSnapshot} into model
+         *               objects.
+         * @return this, for chaining.
+         */
         @NonNull
         public Builder<T> setQuery(@NonNull Query query,
                                    @NonNull Source source,
@@ -96,18 +129,36 @@ public Builder<T> setQuery(@NonNull Query query,
             return this;
         }
 
+        /**
+         * Sets an optional custom {@link DiffUtil.ItemCallback} to compare
+         * {@link DocumentSnapshot} objects.
+         *
+         * The default implementation is {@link DefaultSnapshotDiffCallback}.
+         * 
+         * @return this, for chaining.
+         */
         @NonNull
         public Builder<T> setDiffCallback(@NonNull DiffUtil.ItemCallback<DocumentSnapshot> diffCallback) {
             mDiffCallback = diffCallback;
             return this;
         }
 
+        /**
+         * Sets an optional {@link LifecycleOwner} to control the lifecycle of the adapter. Otherwise,
+         * you must manually call {@link FirestorePagingAdapter#startListening()}
+         * and {@link FirestorePagingAdapter#stopListening()}.
+         *
+         * @return this, for chaining.
+         */
         @NonNull
         public Builder<T> setLifecycleOwner(@NonNull LifecycleOwner owner) {
             mOwner = owner;
             return this;
         }
 
+        /**
+         * Build the {@link FirestorePagingOptions} object.
+         */
         @NonNull
         public FirestorePagingOptions<T> build() {
             if (mData == null || mParser == null) {

firestore/src/main/java/com/firebase/ui/firestore/paging/LoadingState.java

@@ -5,7 +5,7 @@
  */
 public enum LoadingState {
     /**
-     * Loading initial data.Pag
+     * Loading initial data.
      */
     LOADING_INITIAL,