Address Gil's feedback

Author: schmidt-sebastian

packages/firestore/exp/src/api/database.ts

@@ -176,14 +176,14 @@ export class FirebaseFirestore
 
 /**
  * Initializes a new instance of Cloud Firestore with the provided settings.
- * Can only be called before any other methods, including
- * {@link getFirestore()}. If the custom settings are empty, this method is
+ * Can only be called before any other function, including
+ * {@link getFirestore()}. If the custom settings are empty, this function is
  * equivalent to calling {@link getFirestore()}.
  *
- * @param app The {@link FirebaseApp} that the Firestore instance will be
- * associated with.
- * @param settings A settings object to configure the Firestore instance.
- * @return A newly initialized Firestore instance.
+ * @param app The {@link FirebaseApp} with which the `Firestore` instance will
+ * be associated.
+ * @param settings A settings object to configure the `Firestore` instance.
+ * @return A newly initialized `Firestore` instance.
  */
 export function initializeFirestore(
   app: FirebaseApp,
@@ -216,7 +216,7 @@ export function initializeFirestore(
  *
  * @param app The {@link FirebaseApp} instance that the returned Firestore
  * instance is associated with.
- * @return The Firestore instance of the provided app.
+ * @return The `Firestore` instance of the provided app.
  */
 export function getFirestore(app: FirebaseApp): FirebaseFirestore {
   return _getProvider(app, 'firestore-exp').getImmediate() as FirebaseFirestore;
@@ -225,12 +225,12 @@ export function getFirestore(app: FirebaseApp): FirebaseFirestore {
 /**
  * Attempts to enable persistent storage, if possible.
  *
- * Must be called before any other methods (other than
+ * Must be called before any other functions (other than
  * {@link initializeFirestore()}, {@link getFirestore()} or
  * {@link clearIndexedDbPersistence()}.
  *
- * If this fails, enableIndexedDbPersistence() will reject the promise it
- * returns. Note that even after this failure, the firestore instance will
+ * If this fails, `enableIndexedDbPersistence()` will reject the promise it
+ * returns. Note that even after this failure, the `Firestore` instance will
  * remain usable, however offline persistence will be disabled.
  *
  * There are several reasons why this can fail, which can be identified by
@@ -240,7 +240,7 @@ export function getFirestore(app: FirebaseApp): FirebaseFirestore {
  *   * unimplemented: The browser is incompatible with the offline
  *     persistence implementation.
  *
- * @param firestore The Firestore instance to enable persistence for.
+ * @param firestore The `Firestore` instance to enable persistence for.
  * @param persistenceSettings Optional settings object to configure persistence.
  * @return A promise that represents successfully enabling persistent storage.
  */
@@ -283,8 +283,8 @@ export function enableIndexedDbPersistence(
  * shared execution of queries and latency-compensated local document updates
  * across all connected instances.
  *
- * If this fails, enableMultiTabIndexedDbPersistence() will reject the promise
- * it returns. Note that even after this failure, the firestore instance will
+ * If this fails, `enableMultiTabIndexedDbPersistence()` will reject the promise
+ * it returns. Note that even after this failure, the `Firestore` instance will
  * remain usable, however offline persistence will be disabled.
  *
  * There are several reasons why this can fail, which can be identified by
@@ -295,7 +295,7 @@ export function enableIndexedDbPersistence(
  *   * unimplemented: The browser is incompatible with the offline
  *     persistence implementation.
  *
- * @param firestore The Firestore instance to enable persistence for.
+ * @param firestore The `Firestore` instance to enable persistence for.
  * @return A promise that represents successfully enabling persistent
  * storage.
  */
@@ -334,20 +334,21 @@ export function enableMultiTabIndexedDbPersistence(
  * Clears the persistent storage. This includes pending writes and cached
  * documents.
  *
- * Must be called while the firestore instance is not started (after the app is
- * shutdown or when the app is first initialized). On startup, this method must
- * be called before other methods (other than {@link initializeFirestore()} or
- * {@link getFirestore()})). If the firestore instance is still running, the
- * promise will be rejected with the error code of `failed-precondition`.
+ * Must be called while the `Firestore` instance is not started (after the app is
+ * terminated or when the app is first initialized). On startup, this function
+ * must be called before other functions (other than {@link
+ * initializeFirestore()} or {@link getFirestore()})). If the `Firestore`
+ * instance is still running, the promise will be rejected with the error code
+ * of `failed-precondition`.
  *
- * Note: clearIndexedDbPersistence() is primarily intended to help write
+ * Note: `clearIndexedDbPersistence()` is primarily intended to help write
  * reliable tests that use Cloud Firestore. It uses an efficient mechanism for
  * dropping existing data but does not attempt to securely overwrite or
  * otherwise make cached data unrecoverable. For applications that are sensitive
  * to the disclosure of cached data in between user sessions, we strongly
  * recommend not enabling persistence at all.
  *
- * @param firestore The Firestore instance to clear persistence for.
+ * @param firestore The `Firestore` instance to clear persistence for.
  * @return A promise that is resolved when the persistent storage is
  * cleared. Otherwise, the promise is rejected with an error.
  */
@@ -383,7 +384,7 @@ export function clearIndexedDbPersistence(
  * The returned Promise resolves immediately if there are no outstanding writes.
  * Otherwise, the Promise waits for all previously issued writes (including
  * those written in a previous app session), but it does not wait for writes
- * that were added after the method is called. If you want to wait for
+ * that were added after the function is called. If you want to wait for
  * additional writes, call `waitForPendingWrites()` again.
  *
  * Any outstanding `waitForPendingWrites()` Promises are rejected during user
@@ -425,7 +426,7 @@ export function enableNetwork(firestore: FirebaseFirestore): Promise<void> {
 /**
  * Disables network usage for this instance. It can be re-enabled via {@link
  * enableNetwork()}. While the network is disabled, any snapshot listeners,
- * getDoc() or getDocs() calls will return results from cache, and any write
+ * `getDoc()` or `getDocs()` calls will return results from cache, and any write
  * operations will be queued until the network is restored.
  *
  * @return A promise that is resolved once the network has been disabled.
@@ -444,8 +445,8 @@ export function disableNetwork(firestore: FirebaseFirestore): Promise<void> {
 /**
  * Terminates the provided Firestore instance.
  *
- * After calling `terminate()` only the `clearIndexedDbPersistence()` method may
- * be used. Any other method will throw a `FirestoreError`.
+ * After calling `terminate()` only the `clearIndexedDbPersistence()` function
+ * may be used. Any other function will throw a `FirestoreError`.
  *
  * To restart after termination, create a new instance of FirebaseFirestore with
  * {@link getFirestore()}.
@@ -456,9 +457,9 @@ export function disableNetwork(firestore: FirebaseFirestore): Promise<void> {
  * sending these writes to the server.
  *
  * Note: Under normal circumstances, calling `terminate()` is not required. This
- * method is useful only when you want to force this instance to release all of
- * its resources or in combination with `clearIndexedDbPersistence()` to ensure
- * that all local state is destroyed between test runs.
+ * function is useful only when you want to force this instance to release all
+ * of its resources or in combination with `clearIndexedDbPersistence()` to
+ * ensure that all local state is destroyed between test runs.
  *
  * @return A promise that is resolved when the instance has been successfully
  * terminated.

packages/firestore/exp/src/api/reference.ts

@@ -98,10 +98,10 @@ export interface SnapshotListenOptions {
  * Note: `getDoc()` attempts to provide up-to-date data when possible by waiting
  * for data from the server, but it may return cached data or fail if you are
  * offline and the server cannot be reached. To specify this behavior, invoke
- * {@link getDocFromCache()} or @link getDocFromServer()}.
+ * {@link getDocFromCache()} or {@link getDocFromServer()}.
  *
  * @param reference The reference of the document to fetch.
- * @return A Promise resolved with a DocumentSnapshot containing the
+ * @return A Promise resolved with a `DocumentSnapshot` containing the
  * current document contents.
  */
 export function getDoc<T>(
@@ -130,7 +130,7 @@ export function getDoc<T>(
  * Reads the document referred to by this `DocumentReference` from cache.
  * Returns an error if the document is not currently cached.
  *
- * @return A Promise resolved with a DocumentSnapshot containing the
+ * @return A Promise resolved with a `DocumentSnapshot` containing the
  * current document contents.
  */
 export function getDocFromCache<T>(
@@ -163,7 +163,7 @@ export function getDocFromCache<T>(
  * Reads the document referred to by this `DocumentReference` from the server.
  * Returns an error if the network is not available.
  *
- * @return A Promise resolved with a DocumentSnapshot containing the
+ * @return A Promise resolved with a `DocumentSnapshot` containing the
  * current document contents.
  */
 export function getDocFromServer<T>(
@@ -196,7 +196,7 @@ export function getDocFromServer<T>(
  * you are offline and the server cannot be reached. To specify this behavior,
  * invoke {@link getDocsFromCache()} or {@link getDocsFromServer()}.
  *
- * @return A Promise that will be resolved with the results of the Query.
+ * @return A Promise that will be resolved with the results of the query.
  */
 export function getDocs<T>(query: Query<T>): Promise<QuerySnapshot<T>> {
   const firestore = cast(query.firestore, FirebaseFirestore);
@@ -224,7 +224,7 @@ export function getDocs<T>(query: Query<T>): Promise<QuerySnapshot<T>> {
  * Executes the query and returns the results as a `QuerySnapshot` from cache.
  * Returns an error if the document is not currently cached.
  *
- * @return A Promise that will be resolved with the results of the Query.
+ * @return A Promise that will be resolved with the results of the query.
  */
 export function getDocsFromCache<T>(
   query: Query<T>
@@ -244,9 +244,9 @@ export function getDocsFromCache<T>(
 
 /**
  * Executes the query and returns the results as a `QuerySnapshot` from the
- * server. Returns an error if the network is not available..
+ * server. Returns an error if the network is not available.
  *
- * @return A Promise that will be resolved with the results of the Query.
+ * @return A Promise that will be resolved with the results of the query.
  */
 export function getDocsFromServer<T>(
   query: Query<T>
@@ -277,7 +277,7 @@ export function getDocsFromServer<T>(
  * @param reference A reference to the document to write.
  * @param data A map of the fields and values for the document.
  * @return A Promise resolved once the data has been successfully written
- * to the backend (Note that it won't resolve while you're offline).
+ * to the backend (note that it won't resolve while you're offline).
  */
 export function setDoc<T>(
   reference: DocumentReference<T>,
@@ -292,7 +292,7 @@ export function setDoc<T>(
  * @param data A map of the fields and values for the document.
  * @param options An object to configure the set behavior.
  * @return A Promise resolved once the data has been successfully written
- * to the backend (Note that it won't resolve while you're offline).
+ * to the backend (note that it won't resolve while you're offline).
  */
 export function setDoc<T>(
   reference: DocumentReference<T>,
@@ -336,7 +336,7 @@ export function setDoc<T>(
  * update the document. Fields can contain dots to reference nested fields
  * within the document.
  * @return A Promise resolved once the data has been successfully written
- * to the backend (Note that it won't resolve while you're offline).
+ * to the backend (note that it won't resolve while you're offline).
  */
 export function updateDoc(
   reference: DocumentReference<unknown>,
@@ -348,14 +348,14 @@ export function updateDoc(
  * not exist.
  *
  * Nested fields can be updated by providing dot-separated field path
- * strings or by providing FieldPath objects.
+ * strings or by providing `FieldPath` objects.
  *
  * @param reference A reference to the document to update.
  * @param field The first field to update.
  * @param value The first value.
  * @param moreFieldsAndValues Additional key value pairs.
  * @return A Promise resolved once the data has been successfully written
- * to the backend (Note that it won't resolve while you're offline).
+ * to the backend (note that it won't resolve while you're offline).
  */
 export function updateDoc(
   reference: DocumentReference<unknown>,
@@ -408,7 +408,7 @@ export function updateDoc(
  *
  * @param reference A reference to the document to delete.
  * @return A Promise resolved once the document has been successfully
- * deleted from the backend (Note that it won't resolve while you're offline).
+ * deleted from the backend (note that it won't resolve while you're offline).
  */
 export function deleteDoc(
   reference: DocumentReference<unknown>
@@ -424,7 +424,7 @@ export function deleteDoc(
  * Add a new document to specified `CollectionReference` with the given data,
  * assigning it a document ID automatically.
  *
- * @param reference A reference to the Collection to add this document to.
+ * @param reference A reference to the collection to add this document to.
  * @param data An Object containing the data for the new document.
  * @return A Promise resolved with a `DocumentReference` pointing to the
  * newly created document after it has been written to the backend (Note that it
@@ -461,7 +461,7 @@ export function addDoc<T>(
 // integration tests
 
 /**
- * Attaches a listener for DocumentSnapshot events. You may either pass
+ * Attaches a listener for `DocumentSnapshot` events. You may either pass
  * individual `onNext` and `onError` callbacks or pass a single observer
  * object with `next` and `error` callbacks.
  *
@@ -482,7 +482,7 @@ export function onSnapshot<T>(
   }
 ): Unsubscribe;
 /**
- * Attaches a listener for DocumentSnapshot events. You may either pass
+ * Attaches a listener for `DocumentSnapshot` events. You may either pass
  * individual `onNext` and `onError` callbacks or pass a single observer
  * object with `next` and `error` callbacks.
  *
@@ -505,7 +505,7 @@ export function onSnapshot<T>(
   }
 ): Unsubscribe;
 /**
- * Attaches a listener for DocumentSnapshot events. You may either pass
+ * Attaches a listener for `DocumentSnapshot` events. You may either pass
  * individual `onNext` and `onError` callbacks or pass a single observer
  * object with `next` and `error` callbacks.
  *
@@ -529,7 +529,7 @@ export function onSnapshot<T>(
   onCompletion?: () => void
 ): Unsubscribe;
 /**
- * Attaches a listener for DocumentSnapshot events. You may either pass
+ * Attaches a listener for `DocumentSnapshot` events. You may either pass
  * individual `onNext` and `onError` callbacks or pass a single observer
  * object with `next` and `error` callbacks.
  *
@@ -555,7 +555,7 @@ export function onSnapshot<T>(
   onCompletion?: () => void
 ): Unsubscribe;
 /**
- * Attaches a listener for QuerySnapshot events. You may either pass
+ * Attaches a listener for `QuerySnapshot` events. You may either pass
  * individual `onNext` and `onError` callbacks or pass a single observer
  * object with `next` and `error` callbacks. The listener can be cancelled by
  * calling the function that is returned when `onSnapshot` is called.
@@ -577,7 +577,7 @@ export function onSnapshot<T>(
   }
 ): Unsubscribe;
 /**
- * Attaches a listener for QuerySnapshot events. You may either pass
+ * Attaches a listener for `QuerySnapshot` events. You may either pass
  * individual `onNext` and `onError` callbacks or pass a single observer
  * object with `next` and `error` callbacks. The listener can be cancelled by
  * calling the function that is returned when `onSnapshot` is called.
@@ -601,7 +601,7 @@ export function onSnapshot<T>(
   }
 ): Unsubscribe;
 /**
- * Attaches a listener for QuerySnapshot events. You may either pass
+ * Attaches a listener for `QuerySnapshot` events. You may either pass
  * individual `onNext` and `onError` callbacks or pass a single observer
  * object with `next` and `error` callbacks. The listener can be cancelled by
  * calling the function that is returned when `onSnapshot` is called.
@@ -626,7 +626,7 @@ export function onSnapshot<T>(
   onCompletion?: () => void
 ): Unsubscribe;
 /**
- * Attaches a listener for QuerySnapshot events. You may either pass
+ * Attaches a listener for `QuerySnapshot` events. You may either pass
  * individual `onNext` and `onError` callbacks or pass a single observer
  * object with `next` and `error` callbacks. The listener can be cancelled by
  * calling the function that is returned when `onSnapshot` is called.