Update public API docs of FIRFirestore.h and FIRTransactionOptions.h

Author: dconeybe

Firestore/Source/Public/FirebaseFirestore/FIRFirestore.h

@@ -151,10 +151,34 @@ NS_SWIFT_NAME(Firestore)
  * Executes the given updateBlock and then attempts to commit the changes applied within an atomic
  * transaction.
  *
- * This is identical to `runTransactionWithBlock` except that it also accepts "options" that affect
- * how the transaction is executed.
+ * The maximum number of writes allowed in a single transaction is 500, but note that each usage of
+ * `FieldValue.serverTimestamp()`, `FieldValue.arrayUnion()`, `FieldValue.arrayRemove()`, or
+ * `FieldValue.increment()` inside a transaction counts as an additional write.
+ *
+ * In the updateBlock, a set of reads and writes can be performed atomically using the
+ * `Transaction` object passed to the block. After the updateBlock is run, Firestore will attempt
+ * to apply the changes to the server. If any of the data read has been modified outside of this
+ * transaction since being read, then the transaction will be retried by executing the updateBlock
+ * again. If the transaction still fails after the attempting the number of times specified by the
+ * `max_attempts` property of the given `TransactionOptions` object, then the transaction will fail.
+ * If the given `TransactionOptions` is `nil`, then the default `max_attempts` of 5 will be used.
+ *
+ * Since the updateBlock may be executed multiple times, it should avoiding doing anything that
+ * would cause side effects.
+ *
+ * Any value maybe be returned from the updateBlock. If the transaction is successfully committed,
+ * then the completion block will be passed that value. The updateBlock also has an `NSErrorPointer`
+ * out parameter. If this is set, then the transaction will not attempt to commit, and the given
+ * error will be passed to the completion block.
+ *
+ * The `Transaction` object passed to the updateBlock contains methods for accessing documents
+ * 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, the final commit will fail, and the completion block will return an error.
  *
- * @param options The options to use for the transaction.
+ * @param options The transaction options for controlling execution, or `nil` to use the default
+ *     transaction options.
  * @param updateBlock The block to execute within the transaction context.
  * @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.

Firestore/Source/Public/FirebaseFirestore/FIRTransactionOptions.h

@@ -18,14 +18,17 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/** Settings used to configure a `Firestore` instance. */
+/**
+ * Options to customize the behavior of `Firestore.runTransactionWithOptions()`.
+ */
 NS_SWIFT_NAME(TransactionOptions)
 @interface FIRTransactionOptions : NSObject <NSCopying>
 
 /**
- * Creates and returns an empty `FirestoreTransactionOptions` object.
+ * Creates and returns a new `TransactionOptions` object with all properties initialized to their
+ * default values.
  *
- * @return The created `FirestoreTransactionOptions` object.
+ * @return The created `TransactionOptions` object.
  */
 - (instancetype)init NS_DESIGNATED_INITIALIZER;