Improve documentation for merge behavior (#9121)

Author: schmidt-sebastian

Firestore/Source/Public/FirebaseFirestore/FIRDocumentReference.h

@@ -90,7 +90,9 @@ NS_SWIFT_NAME(DocumentReference)
  *
  * @param documentData An `NSDictionary` that contains the fields and data to write to the
  * document.
- * @param merge Whether to merge the provided data into any existing document.
+ * @param merge Whether to merge the provided data into any existing document. If enabled,
+ * all omitted fields remain untouched. If your input sets any field to an empty dictionary, any
+ * nested field at this location is overwritten.
  */
 - (void)setData:(NSDictionary<NSString *, id> *)documentData merge:(BOOL)merge;
 
@@ -106,8 +108,9 @@ NS_SWIFT_NAME(DocumentReference)
  * @param documentData An `NSDictionary` containing the fields that make up the document
  * to be written.
  * @param mergeFields An `NSArray` that contains a list of `NSString` or `FIRFieldPath` elements
- *     specifying which fields to merge. Fields can contain dots to reference nested fields within
- *     the document.
+ * specifying which fields to merge. Fields can contain dots to reference nested fields within
+ * the document. If your input sets any field to an empty dictionary, any nested field at this
+ * location is overwritten.
  */
 - (void)setData:(NSDictionary<NSString *, id> *)documentData mergeFields:(NSArray<id> *)mergeFields;
 

Firestore/Source/Public/FirebaseFirestore/FIRTransaction.h

@@ -54,7 +54,9 @@ NS_SWIFT_NAME(Transaction)
  *
  * @param data An `NSDictionary` that contains the fields and data to write to the document.
  * @param document A reference to the document whose data should be overwritten.
- * @param merge Whether to merge the provided data into any existing document.
+ * @param merge Whether to merge the provided data into any existing document. If enabled,
+ * all omitted fields remain untouched. If your input sets any field to an empty dictionary, any
+ * nested field at this location is overwritten.
  * @return This `FIRTransaction` instance. Used for chaining method calls.
  */
 // clang-format off
@@ -77,8 +79,9 @@ NS_SWIFT_NAME(Transaction)
  * to be written.
  * @param document A reference to the document whose data should be overwritten.
  * @param mergeFields An `NSArray` that contains a list of `NSString` or `FIRFieldPath` elements
- *     specifying which fields to merge. Fields can contain dots to reference nested fields within
- *     the document.
+ * specifying which fields to merge. Fields can contain dots to reference nested fields within
+ * the document.  If your input sets any field to an empty dictionary, any nested field at this
+ * llocation is overwritten.
  * @return This `FIRTransaction` instance. Used for chaining method calls.
  */
 // clang-format off

Firestore/Source/Public/FirebaseFirestore/FIRWriteBatch.h

@@ -57,7 +57,9 @@ NS_SWIFT_NAME(WriteBatch)
  *
  * @param data An `NSDictionary` that contains the fields and data to write to the document.
  * @param document A reference to the document whose data should be overwritten.
- * @param merge Whether to merge the provided data into any existing document.
+ * @param merge Whether to merge the provided data into any existing document. If enabled,
+ * all omitted fields remain untouched. If your input sets any field to an empty dictionary, any
+ * nested field at this location is overwritten.
  * @return This `FIRWriteBatch` instance. Used for chaining method calls.
  */
 // clang-format off
@@ -79,8 +81,9 @@ NS_SWIFT_NAME(WriteBatch)
  * @param data An `NSDictionary` that contains the fields and data to write to the document.
  * @param document A reference to the document whose data should be overwritten.
  * @param mergeFields An `NSArray` that contains a list of `NSString` or `FIRFieldPath` elements
- *     specifying which fields to merge. Fields can contain dots to reference nested fields within
- *     the document.
+ * specifying which fields to merge. Fields can contain dots to reference nested fields within
+ * the document. If your input sets any field to an empty dictionary, any nested field at this
+ * location is overwritten.
  * @return This `FIRWriteBatch` instance. Used for chaining method calls.
  */
 // clang-format off