Add documentation and fix test.

Author: tom-andersen

firebase-firestore/src/androidTest/java/com/google/firebase/firestore/FirestoreTest.java

@@ -38,6 +38,7 @@
 import static org.junit.Assert.assertSame;
 import static org.junit.Assert.assertTrue;
 import static org.junit.Assert.fail;
+import static org.junit.Assume.assumeTrue;
 
 import androidx.test.ext.junit.runners.AndroidJUnit4;
 import com.google.android.gms.tasks.Task;
@@ -1169,13 +1170,11 @@ public void testDifferentDbNamesAreDifferent() {
   }
 
   @Test
-  public void testNamedDbHaveDifferentPersistence()
-      throws ExecutionException, InterruptedException, TimeoutException {
+  public void testNamedDbHaveDifferentPersistence() {
     // TODO: Have backend with named databases created beforehand.
     // Emulator doesn't care if database was created beforehand.
-    if (!isRunningAgainstEmulator()) {
-      return;
-    }
+    assumeTrue(isRunningAgainstEmulator());
+
     // FirebaseFirestore db1 = FirebaseFirestore.getInstance();
     String projectId = provider().projectId();
     FirebaseFirestore db1 =

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

@@ -112,24 +112,61 @@ private static FirebaseApp getDefaultFirebaseApp() {
     return app;
   }
 
+  /**
+   * Returns the existing default {@link FirebaseFirestore} instance that is associated with the
+   * default {@link FirebaseApp}. If no instance exists, initializes a new
+   * instance with default settings.
+   * @param app - The {@link FirebaseApp} instance that the returned {@link FirebaseFirestore}
+   *            instance is associated with.
+   * @param database - The name of database.
+   * @returns The {@link FirebaseFirestore} instance of the provided app.
+   */
   @NonNull
   public static FirebaseFirestore getInstance() {
     return getInstance(getDefaultFirebaseApp(), DatabaseId.DEFAULT_DATABASE_ID);
   }
 
+  /**
+   * Returns the existing default {@link FirebaseFirestore} instance that is associated with the
+   * provided {@link FirebaseApp}. If no instance exists, initializes a new
+   * instance with default settings.
+   * @param app - The {@link FirebaseApp} instance that the returned {@link FirebaseFirestore}
+   *            instance is associated with.
+   * @param database - The name of database.
+   * @returns The {@link FirebaseFirestore} instance of the provided app.
+   */
   @NonNull
   public static FirebaseFirestore getInstance(@NonNull FirebaseApp app) {
     return getInstance(app, DatabaseId.DEFAULT_DATABASE_ID);
   }
 
+  /**
+   * Returns the existing {@link FirebaseFirestore} instance that is associated with the
+   * default {@link FirebaseApp}. If no instance exists, initializes a new
+   * instance with default settings.
+   * @param app - The {@link FirebaseApp} instance that the returned {@link FirebaseFirestore}
+   *            instance is associated with.
+   * @param database - The name of database.
+   * @returns The {@link FirebaseFirestore} instance of the provided app.
+   */
   @NonNull
   public static FirebaseFirestore getInstance(@NonNull String database) {
     return getInstance(getDefaultFirebaseApp(), database);
   }
 
+  /**
+   * Returns the existing {@link FirebaseFirestore} instance that is associated with the
+   * provided {@link FirebaseApp}. If no instance exists, initializes a new
+   * instance with default settings.
+   * @param app - The {@link FirebaseApp} instance that the returned {@link FirebaseFirestore}
+   *            instance is associated with.
+   * @param database - The name of database.
+   * @returns The {@link FirebaseFirestore} instance of the provided app.
+   */
   @NonNull
   public static FirebaseFirestore getInstance(@NonNull FirebaseApp app, @NonNull String database) {
     checkNotNull(app, "Provided FirebaseApp must not be null.");
+    checkNotNull(database, "Provided database name must not be null.");
     FirestoreMultiDbComponent component = app.get(FirestoreMultiDbComponent.class);
     checkNotNull(component, "Firestore component is not present.");
     return component.get(database);