Edit java docs for Firebase App Distribution (#3393)

* Edit java docs for Firebase App Distribution

* Respond to PR review comments

* Responding to PR feedback

Author: rachaprince

firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/AppDistributionRelease.java

@@ -19,13 +19,8 @@
 import com.google.auto.value.AutoValue;
 
 /**
- * This class represents the AppDistributionRelease object returned by checkForUpdate() and
- * updateToLatestRelease()
- *
- * <p>It is an immutable value class implemented by AutoValue.
- *
- * @see <a
- *     href="https://github.com/google/auto/tree/master/value">https://github.com/google/auto/tree/master/value</a>
+ * The release information returned by {@link FirebaseAppDistribution#checkForNewRelease} when a new
+ * version is available for the signed in tester.
  */
 @AutoValue
 public abstract class AppDistributionRelease {
@@ -35,19 +30,19 @@ static Builder builder() {
     return new com.google.firebase.appdistribution.AutoValue_AppDistributionRelease.Builder();
   }
 
-  /** The short bundle version of this build (example 1.0.0) */
+  /** The short bundle version of this build (example 1.0.0). */
   @NonNull
   public abstract String getDisplayVersion();
 
-  /** The version code of this build (example: 123) */
+  /** The version code of this build (example: 123). */
   @NonNull
   public abstract long getVersionCode();
 
-  /** The release notes for this build */
+  /** The release notes for this build. */
   @Nullable
   public abstract String getReleaseNotes();
 
-  /** The binary type for this build */
+  /** The binary type for this build. */
   @NonNull
   public abstract BinaryType getBinaryType();
 

firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/BinaryType.java

@@ -14,8 +14,11 @@
 
 package com.google.firebase.appdistribution;
 
-/** Enum of Android App Binary types, used in AppDistributionRelease */
+/** Enum of Android app binary types, used in {@link AppDistributionRelease} */
 public enum BinaryType {
+  /** Android App Bundle. */
   AAB,
+
+  /** Android Application Package. */
   APK
 }

firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/FirebaseAppDistribution.java

@@ -39,6 +39,15 @@
 import com.google.firebase.inject.Provider;
 import com.google.firebase.installations.FirebaseInstallationsApi;
 
+/**
+ * The Firebase App Distribution API provides methods to update the app to the most recent
+ * pre-release build.
+ *
+ * <p>By default, Firebase App Distribution is automatically initialized.
+ *
+ * <p>Call {@link FirebaseAppDistribution#getInstance()} to get the singleton instance of
+ * FirebaseAppDistribution.
+ */
 public class FirebaseAppDistribution {
 
   private static final int UNKNOWN_RELEASE_FILE_SIZE = -1;
@@ -124,19 +133,25 @@ public class FirebaseAppDistribution {
         FirebaseAppDistributionLifecycleNotifier.getInstance());
   }
 
-  /** @return a FirebaseAppDistribution instance */
+  /** Gets the singleton {@link FirebaseAppDistribution} instance. */
   @NonNull
   public static FirebaseAppDistribution getInstance() {
     return FirebaseApp.getInstance().get(FirebaseAppDistribution.class);
   }
 
   /**
-   * Updates the app to the newest release, if one is available. Returns the release information or
-   * null if no update is found. Performs the following actions: 1. If tester is not signed in,
-   * presents the tester with a Google sign in UI 2. Checks if a newer release is available. If so,
-   * presents the tester with a confirmation dialog to begin the download. 3. For APKs, downloads
-   * the binary and starts an installation intent. 4. For AABs, directs the tester to the Play app
-   * to complete the download and installation.
+   * Updates the app to the newest release, if one is available.
+   *
+   * <p>Returns the release information or null if no update is found. Performs the following
+   * actions:
+   *
+   * <ol>
+   *   <li>If tester is not signed in, presents the tester with a Google sign in UI.
+   *   <li>Checks if a newer release is available. If so, presents the tester with a confirmation
+   *       dialog to begin the download.
+   *   <li>For APKs, downloads the binary and starts an installation intent. For AABs, directs the
+   *       tester to the Play app to complete the download and installation.
+   * </ol>
    */
   @NonNull
   public UpdateTask updateIfNewReleaseAvailable() {
@@ -242,9 +257,8 @@ public Task<Void> signInTester() {
   }
 
   /**
-   * Returns an AppDistributionRelease if one is available for the current signed in tester. If no
-   * update is found, returns null. If tester is not signed in, presents the tester with a Google
-   * sign in UI
+   * Returns an {@link AppDistributionRelease} if an update is available for the current signed in
+   * tester, or {@code null} otherwise.
    */
   @NonNull
   public synchronized Task<AppDistributionRelease> checkForNewRelease() {
@@ -277,12 +291,14 @@ public synchronized Task<AppDistributionRelease> checkForNewRelease() {
   }
 
   /**
-   * Updates app to the newest release. If the newest release is an APK, downloads the binary and
-   * starts an installation If the newest release is an AAB, directs the tester to the Play app to
-   * complete the download and installation.
+   * Updates app to the {@link AppDistributionRelease} returned by {@link #checkForNewRelease}.
+   *
+   * <p>If the newest release is an APK, downloads the binary and starts an installation. If the
+   * newest release is an AAB, directs the tester to the Play app to complete the download and
+   * installation.
    *
-   * <p>cancels task with FirebaseAppDistributionException with UPDATE_NOT_AVAILABLE exception if no
-   * new release is cached from checkForNewRelease
+   * <p>Cancels task with {@link Status#UPDATE_NOT_AVAILABLE} if no new release is cached from
+   * {@link #checkForNewRelease}.
    */
   @NonNull
   public UpdateTask updateApp() {
@@ -324,7 +340,7 @@ private UpdateTask updateApp(boolean showDownloadInNotificationManager) {
     }
   }
 
-  /** Returns true if the App Distribution tester is signed in */
+  /** Returns {@code true} if the App Distribution tester is signed in. */
   public boolean isTesterSignedIn() {
     return this.signInStorage.getSignInStatus();
   }

firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/FirebaseAppDistributionException.java

@@ -19,37 +19,38 @@
 import com.google.firebase.FirebaseException;
 import com.google.firebase.appdistribution.Constants.ErrorMessages;
 
-/** Possible exceptions thrown in FirebaseAppDistribution */
+/** The class for all Exceptions thrown by {@link FirebaseAppDistribution}. */
 public class FirebaseAppDistributionException extends FirebaseException {
+  /** Enum for potential error statuses that caused the {@link FirebaseAppDistributionException}. */
   public enum Status {
     /** Unknown error. */
     UNKNOWN,
 
-    /** Authentication failed */
+    /** The authentication process failed. */
     AUTHENTICATION_FAILURE,
 
-    /** Authentication canceled */
+    /** The authentication process was canceled. */
     AUTHENTICATION_CANCELED,
 
-    /** No Network available to make requests or the request timed out */
+    /** No network is available to make requests or the request timed out. */
     NETWORK_FAILURE,
 
-    /** Download failed */
+    /** The new release failed to download. */
     DOWNLOAD_FAILURE,
 
-    /** Installation failed */
+    /** The new release failed to install. */
     INSTALLATION_FAILURE,
 
-    /** Installation canceled */
+    /** The installation was canceled. */
     INSTALLATION_CANCELED,
 
-    /** Update not available for the current tester and app */
+    /** An update is not available for the current tester and app. */
     UPDATE_NOT_AVAILABLE,
 
-    /** App is in production */
+    /** The app is running in production. */
     APP_RUNNING_IN_PRODUCTION,
 
-    /** Host activity for confirmation dialog destroyed or pushed to the backstack */
+    /** The host activity for a confirmation dialog was destroyed or pushed to the backstack. */
     HOST_ACTIVITY_INTERRUPTED,
   }
 
@@ -86,12 +87,13 @@ public enum Status {
     this.release = release;
   }
 
-  /** Get cached release when error was thrown */
+  /** Returns the release that was ready to be installed when the error was thrown. */
   @Nullable
   public AppDistributionRelease getRelease() {
     return release;
   }
 
+  /** Returns the {@link FirebaseAppDistributionException.Status} that caused the exception. */
   @NonNull
   public Status getErrorCode() {
     return status;

firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/OnProgressListener.java

@@ -18,5 +18,6 @@
 
 /** A listener that is called periodically during execution of the {@link UpdateTask}. */
 public interface OnProgressListener {
+  /** Called periodically for progress update and state changes of the {@link UpdateTask}. */
   void onProgressUpdate(@NonNull UpdateProgress updateState);
 }

firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateProgress.java

@@ -18,7 +18,7 @@
 import androidx.annotation.Nullable;
 import com.google.auto.value.AutoValue;
 
-/** Data class to get download progress for APKs and the status of the update. Used in updateApp. */
+/** Represents a progress update or a final state from updating an app. */
 @AutoValue
 public abstract class UpdateProgress {
 
@@ -28,21 +28,25 @@ static UpdateProgress.Builder builder() {
   }
 
   /**
-   * The number of bytes downloaded so far for the APK. Returns -1 if called on an AAB or if no new
-   * release is available.
+   * The number of bytes downloaded so far for an APK.
+   *
+   * @returns the number of bytes downloaded, or -1 if called when updating to an AAB or if no new
+   *     release is available.
    */
   @NonNull
   public abstract long getApkBytesDownloaded();
 
   /**
-   * The file size of the APK file to download in bytes. Returns -1 if called on an AAB or if no new
-   * release is available.
+   * The file size of the APK file to download in bytes.
+   *
+   * @returns the file size in bytes, or -1 if called when updating to an AAB or if no new release
+   *     is available.
    */
   @NonNull
   public abstract long getApkFileTotalBytes();
 
+  /** Returns the current {@link UpdateStatus} of the update. */
   @NonNull
-  /** returns the current state of the update */
   public abstract UpdateStatus getUpdateStatus();
 
   /** Builder for {@link UpdateProgress}. */

firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateStatus.java

@@ -14,35 +14,35 @@
 
 package com.google.firebase.appdistribution;
 
-/** Enum for possible states during Update, used in UpdateProgress. */
+/** Enum for possible states during Update, used in {@link UpdateProgress}. */
 public enum UpdateStatus {
-  /** Update queued but not started */
+  /** The update is queued but not started. */
   PENDING,
 
-  /** Download in progress */
+  /** The new release download is in progress. */
   DOWNLOADING,
 
-  /** Download completed */
+  /** The new release was downloaded successfully. */
   DOWNLOADED,
 
-  /** Download failed */
+  /** The new release failed to download. */
   DOWNLOAD_FAILED,
 
-  /** Installation canceled */
+  /** The new release installation was canceled. */
   INSTALL_CANCELED,
 
-  /** Installation failed */
+  /** The new release installation failed. */
   INSTALL_FAILED,
 
-  /** AAB flow (directed to Play) */
+  /** The tester was redirected to Play to download an {@link BinaryType#AAB} file. */
   REDIRECTED_TO_PLAY,
 
-  /** Currently on the latest release */
+  /** The tester is currently on the latest release they have access to for the current app. */
   NEW_RELEASE_NOT_AVAILABLE,
 
-  /** Release check failed before download started */
+  /** The call to {@link FirebaseAppDistribution#checkForNewRelease} failed. */
   NEW_RELEASE_CHECK_FAILED,
 
-  /** Customer canceled the update */
+  /** The tester canceled the update. */
   UPDATE_CANCELED,
 }

firebase-appdistribution/src/main/java/com/google/firebase/appdistribution/UpdateTask.java

@@ -19,15 +19,26 @@
 import com.google.android.gms.tasks.Task;
 import java.util.concurrent.Executor;
 
+/**
+ * Represents an asynchronous operation to update an app.
+ *
+ * <p>This task also receives progress and other state change notifications.
+ */
 public abstract class UpdateTask extends Task<Void> {
   /**
-   * Adds a listener that is called periodically while the UpdateTask executes.
+   * Adds a listener that is called periodically while this {@link UpdateTask} executes.
    *
-   * @return this Task
+   * @return this {@link UpdateTask}
    */
   @NonNull
   public abstract UpdateTask addOnProgressListener(@NonNull OnProgressListener listener);
 
+  /**
+   * Adds a listener that is called periodically while {@link UpdateTask} executes.
+   *
+   * @param executor the executor to use to call the listener
+   * @return this {@link UpdateTask}
+   */
   @NonNull
   public abstract UpdateTask addOnProgressListener(
       @Nullable Executor executor, @NonNull OnProgressListener listener);