Add comments

Author: cherylEnkidu

firebase-firestore/src/main/java/com/google/firebase/firestore/FirebaseFirestore.java

@@ -406,6 +406,12 @@ public Task<Void> setIndexConfiguration(@NonNull String json) {
     return client.configureFieldIndexes(parsedIndexes);
   }
 
+  /**
+   * Returns the PersistentCache Index Manager used by this {@code FirebaseFirestore} object.
+   *
+   * @return The {@code PersistentCacheIndexManager} instance or null if local persistent storage is
+   *     not in use.
+   */
   // TODO(csi): Remove the `hide` and scope annotations.
   /** @hide */
   @RestrictTo(RestrictTo.Scope.LIBRARY)

firebase-firestore/src/main/java/com/google/firebase/firestore/PersistentCacheIndexManager.java

@@ -18,6 +18,12 @@
 import androidx.annotation.RestrictTo;
 import com.google.firebase.firestore.core.FirestoreClient;
 
+/**
+ * A {@code PersistentCacheIndexManager} which you can config persistent cache indexes used for
+ * local query execution.
+ *
+ * <p>To use, calling {@link FirebaseFirestore#getPersistentCacheIndexManager()} to get an instance.
+ */
 // TODO(csi): Remove the `hide` and scope annotations.
 /** @hide */
 @RestrictTo(RestrictTo.Scope.LIBRARY)
@@ -29,10 +35,20 @@ public PersistentCacheIndexManager(FirestoreClient client) {
     this.client = client;
   }
 
+  /**
+   * Enables SDK to create persistent cache indexes automatically for local query execution when SDK
+   * believes cache indexes can help improves performance.
+   *
+   * <p>This feature is disabled by default.
+   */
   public void enableIndexAutoCreation() {
     client.enableIndexAutoCreation();
   }
 
+  /**
+   * Stops creating persistent cache indexes automatically for local query execution. The indexes
+   * which have been created by calling {@link #enableIndexAutoCreation()} still take effect.
+   */
   public void disableIndexAutoCreation() {
     client.disableIndexAutoCreation();
   }

firebase-firestore/src/main/java/com/google/firebase/firestore/local/IndexManager.java

@@ -78,6 +78,7 @@ enum IndexType {
   /** Removes the given field index and deletes all index values. */
   void deleteFieldIndex(FieldIndex index);
 
+  /** Creates a full matched field index which serves the given target. */
   void createTargetIndices(Target target);
 
   /**

firebase-firestore/src/main/java/com/google/firebase/firestore/local/LocalDocumentsView.java

@@ -258,6 +258,8 @@ void recalculateAndSaveOverlays(Set<DocumentKey> documentKeys) {
    *
    * @param query The query to match documents against.
    * @param offset Read time and key to start scanning by (exclusive).
+   * @param context A optional tracker to keep a record of important details during database local
+   *     query execution.
    */
   ImmutableSortedMap<DocumentKey, Document> getDocumentsMatchingQuery(
       Query query, IndexOffset offset, @Nullable QueryContext context) {
@@ -271,6 +273,12 @@ ImmutableSortedMap<DocumentKey, Document> getDocumentsMatchingQuery(
     }
   }
 
+  /**
+   * Performs a query against the local view of all documents.
+   *
+   * @param query The query to match documents against.
+   * @param offset Read time and key to start scanning by (exclusive).
+   */
   ImmutableSortedMap<DocumentKey, Document> getDocumentsMatchingQuery(
       Query query, IndexOffset offset) {
     return getDocumentsMatchingQuery(query, offset, null);

firebase-firestore/src/main/java/com/google/firebase/firestore/local/QueryContext.java

@@ -14,9 +14,11 @@
 
 package com.google.firebase.firestore.local;
 
+/** A tracker to keep a record of important details during database local query execution. */
 public class QueryContext {
   public QueryContext() {}
 
+  /** Counts the number of documents passed through during local query execution. */
   private int documentReadCount = 0;
 
   public int getDocumentReadCount() {

firebase-firestore/src/main/java/com/google/firebase/firestore/local/QueryEngine.java

@@ -105,6 +105,10 @@ public ImmutableSortedMap<DocumentKey, Document> getDocumentsMatchingQuery(
     return result;
   }
 
+  /**
+   * Decides whether SDK should create a full matched field index for this query based on query
+   * context and query result size.
+   */
   // TODO(csi): Auto experiment data.
   private void CreateCacheIndexes(Query query, QueryContext context, int resultSize) {
     String decisionStr = "";

firebase-firestore/src/main/java/com/google/firebase/firestore/local/RemoteDocumentCache.java

@@ -91,6 +91,17 @@ interface RemoteDocumentCache {
   Map<DocumentKey, MutableDocument> getDocumentsMatchingQuery(
       Query query, IndexOffset offset, @Nonnull Set<DocumentKey> mutatedKeys);
 
+  /**
+   * Returns the documents that match the given query.
+   *
+   * @param query The query to match against remote documents.
+   * @param offset The read time and document key to start scanning at (exclusive).
+   * @param mutatedKeys The keys of documents who have mutations attached, they should be read
+   *     regardless whether they match the given query.
+   * @param context A optional tracker to keep a record of important details during database local
+   *     query execution.
+   * @return A newly created map with the set of documents in the collection.
+   */
   Map<DocumentKey, MutableDocument> getDocumentsMatchingQuery(
       Query query,
       IndexOffset offset,

firebase-firestore/src/main/java/com/google/firebase/firestore/local/SQLiteRemoteDocumentCache.java

@@ -140,10 +140,7 @@ public Map<DocumentKey, MutableDocument> getAll(Iterable<DocumentKey> documentKe
     while (longQuery.hasMoreSubqueries()) {
       longQuery
           .performNextSubquery()
-          .forEach(
-              row -> {
-                processRowInBackground(backgroundQueue, results, row, /*filter*/ null);
-              });
+          .forEach(row -> processRowInBackground(backgroundQueue, results, row, /*filter*/ null));
     }
     backgroundQueue.drain();
     return results;
@@ -226,6 +223,7 @@ private Map<DocumentKey, MutableDocument> getAll(
             row -> {
               processRowInBackground(backgroundQueue, results, row, filter);
               if (context != null) {
+                // Increases the counter by 1 for every document processed.
                 context.increaseDocumentCount();
               }
             });

firebase-firestore/src/main/java/com/google/firebase/firestore/model/TargetIndexMatcher.java

@@ -192,7 +192,10 @@ public boolean servedByIndex(FieldIndex index) {
     return true;
   }
 
+  /** Returns a full matched field index for this target. */
   public FieldIndex BuildTargetIndex() {
+    // We want to make sure only one segment created for one field. For example, in case like
+    // a == 3 and a > 2, index, a ASCENDING, will only be created once.
     Set<FieldPath> uniqueFields = new HashSet<>();
     List<FieldIndex.Segment> segments = new ArrayList<>();
 

firebase-firestore/src/test/java/com/google/firebase/firestore/local/CountingQueryEngine.java

@@ -180,7 +180,7 @@ public Map<DocumentKey, MutableDocument> getAll(
 
       @Override
       public Map<DocumentKey, MutableDocument> getDocumentsMatchingQuery(
-          Query query, IndexOffset offset, Set<DocumentKey> mutatedKeys) {
+          Query query, IndexOffset offset, @NonNull Set<DocumentKey> mutatedKeys) {
         return getDocumentsMatchingQuery(query, offset, mutatedKeys, null);
       }