Porting doc changes from the Web API (#178)

Author: schmidt-sebastian

handwritten/firestore/src/reference.js

@@ -404,8 +404,8 @@ class DocumentReference {
    * specified in its data argument. Fields omitted from this set() call
    * remain untouched.
    * @param {Array.<string|FieldPath>=} options.mergeFields - If provided,
-   * set() only replaces the specified field paths. All data at the specified
-   * field paths is fully replaced, while the remaining fields remain untouched.
+   * set() only replaces the specified field paths. Any field path that is not
+   * specified is ignored and remains untouched.
    * @returns {Promise.<WriteResult>} A Promise that resolves with the
    * write time of this set.
    *

handwritten/firestore/src/transaction.js

@@ -187,8 +187,8 @@ class Transaction {
    * specified in its data argument. Fields omitted from this set() call
    * remain untouched.
    * @param {Array.<string|FieldPath>=} options.mergeFields - If provided,
-   * set() only replaces the specified field paths. All data at the specified
-   * field paths is fully replaced, while the remaining fields remain untouched.
+   * set() only replaces the specified field paths. Any field path that is not
+   * specified is ignored and remains untouched.
    * @returns {Transaction} This Transaction instance. Used for
    * chaining method calls.
    *

handwritten/firestore/src/write-batch.js

@@ -263,8 +263,8 @@ class WriteBatch {
    * specified in its data argument. Fields omitted from this set() call
    * remain untouched.
    * @param {Array.<string|FieldPath>=} options.mergeFields - If provided,
-   * set() only replaces the specified field paths. All data at the specified
-   * field paths is fully replaced, while the remaining fields remain untouched.
+   * set() only replaces the specified field paths. Any field path that is not
+   * specified is ignored and remains untouched.
    * @returns {WriteBatch} This WriteBatch instance. Used for chaining
    * method calls.
    *

handwritten/firestore/types/firestore.d.ts

@@ -365,20 +365,23 @@ declare namespace FirebaseFirestore {
    * An options object that configures the behavior of `set()` calls in
    * `DocumentReference`, `WriteBatch` and `Transaction`. These calls can be
    * configured to perform granular merges instead of overwriting the target
-   * documents in their entirety by providing a `SetOptions` with `merge: true`.
+   * documents in their entirety.
    */
   export interface SetOptions {
     /**
-     * Changes the behavior of a set() call to deeply merge the values specified
+     * Changes the behavior of a set() call to only replace the values specified
      * in its data argument. Fields omitted from the set() call remain
      * untouched.
      */
     readonly merge?: boolean;
 
     /**
-     * Changes the behavior of set() calls to only replace the specified
-     * field paths. All data at the specified field paths is fully replaced, 
-     * while the remaining fields remain untouched.
+     * Changes the behavior of set() calls to only replace the specified field
+     * paths. Any field path that is not specified is ignored and remains
+     * untouched.
+     *
+     * It is an error to pass a SetOptions object to a set() call that is
+     * missing a value for any of the fields specified here.
      */
     readonly mergeFields?: (string|FieldPath)[];
   }