Add some comments, switch the order of indexes in events.

Change-Id: I27a584c7fec5ef89feb4a0e171a24e8babac99ea

Author: samtstern

common/src/main/java/com/firebase/ui/common/BaseSnapshotParser.java

@@ -1,6 +1,11 @@
 package com.firebase.ui.common;
 
-
+/**
+ * Common interface for snapshot parsers.
+ *
+ * @param <S> snapshot type.
+ * @param <T> parsed object type.
+ */
 public interface BaseSnapshotParser<S, T> {
 
     /**

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

@@ -4,22 +4,61 @@
 import com.google.firebase.firestore.FirebaseFirestoreException;
 
 /**
+ * Listener for changes to a {@link FirestoreArray}.
  * TODO: This could be a common interface, it just needs to know about the snapshot and error types.
  */
 public interface ChangeEventListener {
 
+    /**
+     * The type of change to an element of the array,
+     */
     enum Type {
+
+        /**
+         * An element was added to the array.
+         */
         ADDED,
+
+        /**
+         * An element was removed from the array.
+         */
         REMOVED,
+
+        /**
+         * An element in the array has new content.
+         */
         MODIFIED,
+
+        /**
+         * An element in the array has a new position, and also new content.
+         */
         MOVED
     }
 
+    /**
+     * A callback for when a child event occurs in a FirestoreArray.
+     * @param type      The type of the event.
+     * @param snapshot  The {@link DocumentSnapshot} of the changed child.
+     * @param newIndex  The new index of the element, or -1 of it is no longer
+     * @param oldIndex  The previous index of the element, or -1 if it was not
+*                  previously tracked.
+     */
     void onChildChanged(Type type, DocumentSnapshot snapshot,
-                        int oldIndex, int newIndex);
+                        int newIndex, int oldIndex);
 
+    /**
+     * Callback triggered after all child events in a particular snapshot have been
+     * processed.
+     * <p>
+     * Useful for batch events, such as removing a loading indicator after initial load
+     * or a large update batch.
+     */
     void onDataChanged();
 
+    /**
+     * Callback when an error has been detected in the underlying Firestore query listener.
+     * @param e the error that occurred.
+     */
     void onError(FirebaseFirestoreException e);
 
 }

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

@@ -15,7 +15,7 @@
 import java.util.List;
 
 /**
- * TODO(samstern): Document
+ * Exposes a Firestore query as an observable list of objects.
  */
 public class FirestoreArray<T>
         extends BaseObservableSnapshotArray<DocumentSnapshot, ChangeEventListener, T>
@@ -96,7 +96,7 @@ private void onDocumentAdded(DocumentChange change) {
         // Add the document to the set
         mSnapshots.add(change.getNewIndex(), change.getDocument());
         notifyOnChildChanged(ChangeEventListener.Type.ADDED, change.getDocument(),
-                -1, change.getNewIndex());
+                change.getNewIndex(), -1);
     }
 
     private void onDocumentRemoved(DocumentChange change) {
@@ -108,7 +108,7 @@ private void onDocumentRemoved(DocumentChange change) {
         // Remove the document from the set
         mSnapshots.remove(change.getOldIndex());
         notifyOnChildChanged(ChangeEventListener.Type.REMOVED, change.getDocument(),
-                change.getOldIndex(), -1);
+                -1, change.getOldIndex());
     }
 
     private void onDocumentModified(DocumentChange change) {
@@ -121,14 +121,14 @@ private void onDocumentModified(DocumentChange change) {
 
             mSnapshots.set(change.getOldIndex(), change.getDocument());
             notifyOnChildChanged(ChangeEventListener.Type.MODIFIED, change.getDocument(),
-                    change.getOldIndex(), change.getNewIndex());
+                    change.getNewIndex(), change.getOldIndex());
         } else {
             Log.d(TAG, "Modified (moved): " + change.getOldIndex() + " --> " + change.getNewIndex());
 
             mSnapshots.remove(change.getOldIndex());
             mSnapshots.add(change.getNewIndex(), change.getDocument());
             notifyOnChildChanged(ChangeEventListener.Type.MOVED, change.getDocument(),
-                    change.getOldIndex(), change.getNewIndex());
+                    change.getNewIndex(), change.getOldIndex());
         }
     }
 
@@ -157,11 +157,10 @@ private void stopListening() {
 
     private void notifyOnChildChanged(ChangeEventListener.Type type,
                                       DocumentSnapshot snapshot,
-                                      int oldIndex,
-                                      int newIndex) {
+                                      int newIndex, int oldIndex) {
 
         for (ChangeEventListener listener : mListeners) {
-            listener.onChildChanged(type, snapshot, oldIndex, newIndex);
+            listener.onChildChanged(type, snapshot, newIndex, oldIndex);
         }
     }
 

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

@@ -41,7 +41,7 @@ public int getItemCount() {
 
     @Override
     public void onChildChanged(Type type, DocumentSnapshot snapshot,
-                               int oldIndex, int newIndex) {
+                               int newIndex, int oldIndex) {
 
         switch (type) {
             case ADDED:

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

@@ -4,8 +4,6 @@
 import com.google.firebase.firestore.DocumentSnapshot;
 
 /**
- * TODO
+ * Base interface for a {@link BaseSnapshotParser} for {@link DocumentSnapshot}.
  */
-public interface SnapshotParser<T> extends BaseSnapshotParser<DocumentSnapshot, T> {
-
-}
+public interface SnapshotParser<T> extends BaseSnapshotParser<DocumentSnapshot, T> {}