@@ -151,10 +151,34 @@ NS_SWIFT_NAME(Firestore)
151
151
* Executes the given updateBlock and then attempts to commit the changes applied within an atomic
152
152
* transaction.
153
153
*
154
- * This is identical to `runTransactionWithBlock` except that it also accepts "options" that affect
155
- * how the transaction is executed.
154
+ * The maximum number of writes allowed in a single transaction is 500, but note that each usage of
155
+ * `FieldValue.serverTimestamp()`, `FieldValue.arrayUnion()`, `FieldValue.arrayRemove()`, or
156
+ * `FieldValue.increment()` inside a transaction counts as an additional write.
157
+ *
158
+ * In the updateBlock, a set of reads and writes can be performed atomically using the
159
+ * `Transaction` object passed to the block. After the updateBlock is run, Firestore will attempt
160
+ * to apply the changes to the server. If any of the data read has been modified outside of this
161
+ * transaction since being read, then the transaction will be retried by executing the updateBlock
162
+ * again. If the transaction still fails after the attempting the number of times specified by the
163
+ * `max_attempts` property of the given `TransactionOptions` object, then the transaction will fail.
164
+ * If the given `TransactionOptions` is `nil`, then the default `max_attempts` of 5 will be used.
165
+ *
166
+ * Since the updateBlock may be executed multiple times, it should avoiding doing anything that
167
+ * would cause side effects.
168
+ *
169
+ * Any value maybe be returned from the updateBlock. If the transaction is successfully committed,
170
+ * then the completion block will be passed that value. The updateBlock also has an `NSErrorPointer`
171
+ * out parameter. If this is set, then the transaction will not attempt to commit, and the given
172
+ * error will be passed to the completion block.
173
+ *
174
+ * The `Transaction` object passed to the updateBlock contains methods for accessing documents
175
+ * and collections. Unlike other firestore access, data accessed with the transaction will not
176
+ * reflect local changes that have not been committed. For this reason, it is required that all
177
+ * reads are performed before any writes. Transactions must be performed while online. Otherwise,
178
+ * reads will fail, the final commit will fail, and the completion block will return an error.
156
179
*
157
- * @param options The options to use for the transaction.
180
+ * @param options The transaction options for controlling execution, or `nil` to use the default
181
+ * transaction options.
158
182
* @param updateBlock The block to execute within the transaction context.
159
183
* @param completion The block to call with the result or error of the transaction. This
160
184
* block will run even if the client is offline, unless the process is killed.
0 commit comments