Fix comments and add api.txt change.

Author: tom-andersen

firebase-firestore/api.txt

@@ -152,6 +152,7 @@ package com.google.firebase.firestore {
     method @NonNull public com.google.firebase.firestore.LoadBundleTask loadBundle(@NonNull java.nio.ByteBuffer);
     method @NonNull public com.google.android.gms.tasks.Task<java.lang.Void> runBatch(@NonNull com.google.firebase.firestore.WriteBatch.Function);
     method @NonNull public <TResult> com.google.android.gms.tasks.Task<TResult> runTransaction(@NonNull com.google.firebase.firestore.Transaction.Function<TResult>);
+    method @NonNull public <TResult> com.google.android.gms.tasks.Task<TResult> runTransaction(@NonNull com.google.firebase.firestore.TransactionOptions, @NonNull com.google.firebase.firestore.Transaction.Function<TResult>);
     method public void setFirestoreSettings(@NonNull com.google.firebase.firestore.FirebaseFirestoreSettings);
     method @NonNull public com.google.android.gms.tasks.Task<java.lang.Void> setIndexConfiguration(@NonNull String);
     method public static void setLoggingEnabled(boolean);
@@ -387,6 +388,17 @@ package com.google.firebase.firestore {
     method @Nullable public TResult apply(@NonNull com.google.firebase.firestore.Transaction) throws com.google.firebase.firestore.FirebaseFirestoreException;
   }
 
+  public final class TransactionOptions {
+    method public int getMaxAttempts();
+  }
+
+  public static final class TransactionOptions.Builder {
+    ctor public TransactionOptions.Builder();
+    ctor public TransactionOptions.Builder(@NonNull com.google.firebase.firestore.TransactionOptions);
+    method @NonNull public com.google.firebase.firestore.TransactionOptions build();
+    method @NonNull public com.google.firebase.firestore.TransactionOptions.Builder setMaxAttempts(int);
+  }
+
   public class WriteBatch {
     method @NonNull public com.google.android.gms.tasks.Task<java.lang.Void> commit();
     method @NonNull public com.google.firebase.firestore.WriteBatch delete(@NonNull com.google.firebase.firestore.DocumentReference);

firebase-firestore/src/main/java/com/google/firebase/firestore/FirebaseFirestore.java

@@ -405,9 +405,10 @@ public Query collectionGroup(@NonNull String collectionId) {
   }
 
   /**
-   * Executes the given updateFunction and then attempts to commit the changes applied within the
-   * transaction. If any document read within the transaction has changed, the updateFunction will
-   * be retried. If it fails to commit after 5 attempts, the transaction will fail.
+   * Executes the given {@code updateFunction} and then attempts to commit the changes applied
+   * within the transaction. If any document read within the transaction has changed, the
+   * updateFunction will be retried. If it fails to commit after 5 attempts, the transaction will
+   * fail.
    *
    * <p>The maximum number of writes allowed in a single transaction is 500, but note that each
    * usage of {@link FieldValue#serverTimestamp()}, {@link FieldValue#arrayUnion(Object...)}, {@link
@@ -438,9 +439,10 @@ private <ResultT> Task<ResultT> runTransaction(
   }
 
   /**
-   * Executes the given updateFunction and then attempts to commit the changes applied within the
-   * transaction. If any document read within the transaction has changed, the updateFunction will
-   * be retried. If it fails to commit after 5 attempts, the transaction will fail.
+   * Executes the given {@code updateFunction} and then attempts to commit the changes applied
+   * within the transaction. If any document read within the transaction has changed, the
+   * updateFunction will be retried. If it fails to commit after 5 attempts, the transaction will
+   * fail.
    *
    * @param updateFunction The function to execute within the transaction context.
    * @return The task returned from the updateFunction.
@@ -452,12 +454,12 @@ public <TResult> Task<TResult> runTransaction(
   }
 
   /**
-   * Executes the given updateFunction and then attempts to commit the changes applied within the
-   * transaction. If any document read within the transaction has changed, the updateFunction will
-   * be retried. If it fails to commit after the maxmimum number of attempts specified in
-   * transactionOptions, the transaction will fail.
+   * Executes the given {@code updateFunction} and then attempts to commit the changes applied
+   * within the transaction. If any document read within the transaction has changed, the
+   * updateFunction will be retried. If it fails to commit after the maxmimum number of attempts
+   * specified in transactionOptions, the transaction will fail.
    *
-   * @param options The function to execute within the transaction context.
+   * @param options The transaction options for controlling execution.
    * @param updateFunction The function to execute within the transaction context.
    * @return The task returned from the updateFunction.
    */

firebase-firestore/src/main/java/com/google/firebase/firestore/TransactionOptions.java

@@ -17,7 +17,8 @@
 import androidx.annotation.NonNull;
 
 /**
- * Parameter for {@link FirebaseFirestore#runTransaction(TransactionOptions, Transaction.Function)}.
+ * Options to customize transaction behavior for {@link
+ * FirebaseFirestore#runTransaction(TransactionOptions, Transaction.Function)}.
  */
 public final class TransactionOptions {
 
@@ -46,9 +47,12 @@ public Builder(@NonNull TransactionOptions options) {
     }
 
     /**
-     * Set maximum number of attempts to commit, after which transaction fails. Default is 5.
+     * Set maximum number of attempts to commit, after which transaction fails.
      *
-     * @return this builder
+     * <p>The default value is 5. Setting the value to less than 1 will result in an {@link
+     * IllegalArgumentException}.
+     *
+     * @return This builder
      */
     @NonNull
     public Builder setMaxAttempts(int maxAttempts) {
@@ -60,7 +64,7 @@ public Builder setMaxAttempts(int maxAttempts) {
     /**
      * Build the {@code TransactionOptions} object.
      *
-     * @return the built {@code TransactionOptions} object
+     * @return The built {@code TransactionOptions} object
      */
     @NonNull
     public TransactionOptions build() {
@@ -71,7 +75,7 @@ public TransactionOptions build() {
   /**
    * Get maximum number of attempts to commit, after which transaction fails. Default is 5.
    *
-   * @return maximum number of attempts
+   * @return The maximum number of attempts
    */
   public int getMaxAttempts() {
     return maxAttempts;