add completion execution guarantees to firestore write ops (#481)

4 files changed, 27 insertions, 12 deletions

diff --git a/Firestore/Source/Public/FIRCollectionReference.h b/Firestore/Source/Public/FIRCollectionReference.h
index ba3389f..bc9a56a 100644
--- a/Firestore/Source/Public/FIRCollectionReference.h
+++ b/Firestore/Source/Public/FIRCollectionReference.h
@@ -81,7 +81,9 @@ NS_SWIFT_NAME(CollectionReference)
  * automatically.
  *
  * @param data An `NSDictionary` containing the data for the new document.
- * @param completion A block to execute once the document has been successfully written.
+ * @param completion A block to execute once the document has been successfully written to
+ *     the server. This block will not be called while the client is offline, though local
+ *     changes will be visible immediately.
  *
  * @return A `FIRDocumentReference` pointing to the newly created document.
  */
diff --git a/Firestore/Source/Public/FIRDocumentReference.h b/Firestore/Source/Public/FIRDocumentReference.h
index bd6d7b8..439e727 100644
--- a/Firestore/Source/Public/FIRDocumentReference.h
+++ b/Firestore/Source/Public/FIRDocumentReference.h
@@ -121,8 +121,10 @@ NS_SWIFT_NAME(DocumentReference)
  * is created. If a document already exists, it is overwritten.
  *
  * @param documentData An `NSDictionary` containing the fields that make up the document
- * to be written.
- * @param completion A block to execute once the document has been successfully written.
+ *     to be written.
+ * @param completion A block to execute once the document has been successfully written to the
+ *     server. This block will not be called while the client is offline, though local
+ *     changes will be visible immediately.
  */
 - (void)setData:(NSDictionary<NSString *, id> *)documentData
      completion:(nullable void (^)(NSError *_Nullable error))completion;
@@ -135,7 +137,9 @@ NS_SWIFT_NAME(DocumentReference)
  * @param documentData An `NSDictionary` containing the fields that make up the document
  * to be written.
  * @param options A `FIRSetOptions` used to configure the set behavior.
- * @param completion A block to execute once the document has been successfully written.
+ * @param completion A block to execute once the document has been successfully written to the
+ *     server. This block will not be called while the client is offline, though local
+ *     changes will be visible immediately.
  */
 - (void)setData:(NSDictionary<NSString *, id> *)documentData
         options:(FIRSetOptions *)options
@@ -146,7 +150,7 @@ NS_SWIFT_NAME(DocumentReference)
  * If the document does not exist, the update fails (specify a completion block to be notified).
  *
  * @param fields An `NSDictionary` containing the fields (expressed as an `NSString` or
- * `FIRFieldPath`) and values with which to update the document.
+ *     `FIRFieldPath`) and values with which to update the document.
  */
 - (void)updateData:(NSDictionary<id, id> *)fields;
 
@@ -155,9 +159,12 @@ NS_SWIFT_NAME(DocumentReference)
  * does not exist, the update fails and the specified completion block receives an error.
  *
  * @param fields An `NSDictionary` containing the fields (expressed as an `NSString` or
- * `FIRFieldPath`) and values with which to update the document.
+ *     `FIRFieldPath`) and values with which to update the document.
  * @param completion A block to execute when the update is complete. If the update is successful the
- * error parameter will be nil, otherwise it will give an indication of how the update failed.
+ *     error parameter will be nil, otherwise it will give an indication of how the update failed.
+ *     This block will only execute when the client is online and the commit has completed against
+ *     the server. The completion handler will not be called when the device is offline, though
+ *     local changes will be visible immediately.
  */
 - (void)updateData:(NSDictionary<id, id> *)fields
         completion:(nullable void (^)(NSError *_Nullable error))completion;
@@ -171,7 +178,9 @@ NS_SWIFT_NAME(DocumentReference)
 /**
  * Deletes the document referred to by this `FIRDocumentReference`.
  *
- * @param completion A block to execute once the document has been successfully deleted.
+ * @param completion A block to execute once the document has been successfully written to the
+ *     server. This block will not be called while the client is offline, though local
+ *     changes will be visible immediately.
  */
 // clang-format off
 - (void)deleteDocumentWithCompletion:(nullable void (^)(NSError *_Nullable error))completion
diff --git a/Firestore/Source/Public/FIRFirestore.h b/Firestore/Source/Public/FIRFirestore.h
index 0935917..91a96a5 100644
--- a/Firestore/Source/Public/FIRFirestore.h
+++ b/Firestore/Source/Public/FIRFirestore.h
@@ -115,10 +115,11 @@ NS_SWIFT_NAME(Firestore)
  * and collections. Unlike other firestore access, data accessed with the transaction will not
  * reflect local changes that have not been committed. For this reason, it is required that all
  * reads are performed before any writes. Transactions must be performed while online. Otherwise,
- * reads will fail, and the final commit will fail.
+ * reads will fail, the final commit will fail, and the completion block will return an error.
  *
  * @param updateBlock The block to execute within the transaction context.
- * @param completion The block to call with the result or error of the transaction.
+ * @param completion The block to call with the result or error of the transaction. This
+ *     block will run even if the client is offline, unless the process is killed.
  */
 - (void)runTransactionWithBlock:(id _Nullable (^)(FIRTransaction *, NSError **))updateBlock
                      completion:(void (^)(id _Nullable result, NSError *_Nullable error))completion;
diff --git a/Firestore/Source/Public/FIRWriteBatch.h b/Firestore/Source/Public/FIRWriteBatch.h
index a74d451..5f0034c 100644
--- a/Firestore/Source/Public/FIRWriteBatch.h
+++ b/Firestore/Source/Public/FIRWriteBatch.h
@@ -73,7 +73,7 @@ NS_SWIFT_NAME(WriteBatch)
  * If document does not exist, the write batch will fail.
  *
  * @param fields An `NSDictionary` containing the fields (expressed as an `NSString` or
- * `FIRFieldPath`) and values with which to update the document.
+ *     `FIRFieldPath`) and values with which to update the document.
  * @param document A reference to the document whose data should be updated.
  * @return This `FIRWriteBatch` instance. Used for chaining method calls.
  */
@@ -96,7 +96,10 @@ NS_SWIFT_NAME(WriteBatch)
  * Commits all of the writes in this write batch as a single atomic unit.
  *
  * @param completion A block to be called once all of the writes in the batch have been
- * successfully written to the backend as an atomic unit.
+ *     successfully written to the backend as an atomic unit. This block will only execute
+ *     when the client is online and the commit has completed against the server. The
+ *     completion handler will not be called when the device is offline, though local
+ *     changes will be visible immediately.
  */
 - (void)commitWithCompletion:(void (^)(NSError *_Nullable error))completion;