Feedback

Author: schmidt-sebastian

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

@@ -95,7 +95,7 @@ export interface SnapshotListenOptions {
 /**
  * Reads the document referred to by this `DocumentReference`.
  *
- * Note: getDoc() attempts to provide up-to-date data when possible by waiting
+ * 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()}.
@@ -128,7 +128,7 @@ export function getDoc<T>(
 
 /**
  * Reads the document referred to by this `DocumentReference` from cache.
- * Returns an error of the document is not currently cached.
+ * Returns an error if the document is not currently cached.
  *
  * @return A Promise resolved with a DocumentSnapshot containing the
  * current document contents.
@@ -191,10 +191,10 @@ export function getDocFromServer<T>(
 /**
  * Executes the query and returns the results as a `QuerySnapshot`.
  *
- * Note: getDocs() 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 getDocsFromCache()} or {@link getDocsFromServer()}.
+ * Note: `getDocs()` 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 getDocsFromCache()} or {@link getDocsFromServer()}.
  *
  * @return A Promise that will be resolved with the results of the Query.
  */
@@ -222,7 +222,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 of the document is not currently cached.
+ * Returns an error if the document is not currently cached.
  *
  * @return A Promise that will be resolved with the results of the Query.
  */
@@ -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.
+ * 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.
+ * 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.
+ * to the backend (Note that it won't resolve while you're offline).
  */
 export function updateDoc(
   reference: DocumentReference<unknown>,
@@ -355,7 +355,7 @@ export function updateDoc(
  * @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.
+ * 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.
+ * deleted from the backend (Note that it won't resolve while you're offline).
  */
 export function deleteDoc(
   reference: DocumentReference<unknown>
@@ -427,7 +427,8 @@ export function deleteDoc(
  * @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.
+ * newly created document after it has been written to the backend (Note that it
+ * won't resolve while you're offline).
  */
 export function addDoc<T>(
   reference: CollectionReference<T>,

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

@@ -450,7 +450,7 @@ export class QuerySnapshot<T = DocumentData> {
  * Returns true if the provided snapshots are equal.
  *
  * @param left A snapshot to compare.
- * @param right A snapshot` to compare.
+ * @param right A snapshot to compare.
  * @return true if the snapshots are equal.
  */
 export function snapshotEqual<T>(

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

@@ -84,8 +84,8 @@ export class Transaction extends LiteTransaction {
  * @param updateFunction The function to execute within the transaction context.
  * @return If the transaction completed successfully or was explicitly aborted
  * (the `updateFunction` returned a failed promise), the promise returned by the
- * updateFunction is returned here. Else, if the transaction failed, a rejected
- * promise with the corresponding failure error will be returned.
+ * `updateFunction `is returned here. Otherwise, if the transaction failed, a
+ * rejected promise with the corresponding failure error is returned.
  */
 export function runTransaction<T>(
   firestore: FirebaseFirestore,

packages/firestore/lite/src/api/bytes.ts

@@ -29,10 +29,10 @@ export class Bytes {
   }
 
   /**
-   * Creates a new Bytes object from the given Base64 string, converting it to
+   * Creates a new `Bytes` object from the given Base64 string, converting it to
    * bytes.
    *
-   * @param base64 The Base64 string used to create the Blob object.
+   * @param base64 The Base64 string used to create the `Bytes` object.
    */
   static fromBase64String(base64: string): Bytes {
     try {
@@ -46,9 +46,9 @@ export class Bytes {
   }
 
   /**
-   * Creates a new Bytes object from the given Uint8Array.
+   * Creates a new `Bytes` object from the given Uint8Array.
    *
-   * @param array The Uint8Array used to create the Blob object.
+   * @param array The Uint8Array used to create the `Bytes` object.
    */
   static fromUint8Array(array: Uint8Array): Bytes {
     return new Bytes(ByteString.fromUint8Array(array));
@@ -57,7 +57,7 @@ export class Bytes {
   /**
    * Returns the underlying bytes as a Base64-encoded string.
    *
-   * @return The Base64-encoded string created from the Bytes object.
+   * @return The Base64-encoded string created from the `Bytes` object.
    */
   toBase64(): string {
     return this._byteString.toBase64();
@@ -66,16 +66,16 @@ export class Bytes {
   /**
    * Returns the underlying bytes in a new Uint8Array.
    *
-   * @return The Uint8Array created from the Bytes object.
+   * @return The Uint8Array created from the `Bytes` object.
    */
   toUint8Array(): Uint8Array {
     return this._byteString.toUint8Array();
   }
 
   /**
-   * Returns a string representation of the Bytes object.
+   * Returns a string representation of the `Bytes` object.
    *
-   * @return A string representation of the Bytes object.
+   * @return A string representation of the `Bytes` object.
    */
   toString(): string {
     return 'Bytes(base64: ' + this.toBase64() + ')';

packages/firestore/lite/src/api/field_value.ts

@@ -65,7 +65,7 @@ export function serverTimestamp(): FieldValue {
  * containing exactly the specified elements.
  *
  * @param elements The elements to union into the array.
- * @return The FieldValue sentinel for use in a call to `setDoc()` or
+ * @return The `FieldValue` sentinel for use in a call to `setDoc()` or
  * `updateDoc()`.
  */
 export function arrayUnion(...elements: unknown[]): FieldValue {
@@ -83,7 +83,7 @@ export function arrayUnion(...elements: unknown[]): FieldValue {
  * already an array it will be overwritten with an empty array.
  *
  * @param elements The elements to remove from the array.
- * @return The FieldValue sentinel for use in a call to `setDoc()` or
+ * @return The `FieldValue` sentinel for use in a call to `setDoc()` or
  * `updateDoc()`
  */
 export function arrayRemove(...elements: unknown[]): FieldValue {
@@ -109,7 +109,7 @@ export function arrayRemove(...elements: unknown[]): FieldValue {
  * yet exist, the transformation sets the field to the given value.
  *
  * @param n The value to increment by.
- * @return The FieldValue sentinel for use in a call to `setDoc()` or
+ * @return The `FieldValue` sentinel for use in a call to `setDoc()` or
  * `updateDoc()`
  */
 export function increment(n: number): FieldValue {