Skip to content

Commit 6646bca

Browse files
committed
Update public API docs of FIRFirestore.h and FIRTransactionOptions.h
1 parent 0fe625c commit 6646bca

File tree

2 files changed

+33
-6
lines changed

2 files changed

+33
-6
lines changed

Firestore/Source/Public/FirebaseFirestore/FIRFirestore.h

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -151,10 +151,34 @@ NS_SWIFT_NAME(Firestore)
151151
* Executes the given updateBlock and then attempts to commit the changes applied within an atomic
152152
* transaction.
153153
*
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.
156179
*
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.
158182
* @param updateBlock The block to execute within the transaction context.
159183
* @param completion The block to call with the result or error of the transaction. This
160184
* block will run even if the client is offline, unless the process is killed.

Firestore/Source/Public/FirebaseFirestore/FIRTransactionOptions.h

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,17 @@
1818

1919
NS_ASSUME_NONNULL_BEGIN
2020

21-
/** Settings used to configure a `Firestore` instance. */
21+
/**
22+
* Options to customize the behavior of `Firestore.runTransactionWithOptions()`.
23+
*/
2224
NS_SWIFT_NAME(TransactionOptions)
2325
@interface FIRTransactionOptions : NSObject <NSCopying>
2426

2527
/**
26-
* Creates and returns an empty `FirestoreTransactionOptions` object.
28+
* Creates and returns a new `TransactionOptions` object with all properties initialized to their
29+
* default values.
2730
*
28-
* @return The created `FirestoreTransactionOptions` object.
31+
* @return The created `TransactionOptions` object.
2932
*/
3033
- (instancetype)init NS_DESIGNATED_INITIALIZER;
3134

0 commit comments

Comments
 (0)