Minor API doc updates (suggested by docs team) (firebase#87)

Author: hiranya911

src/main/java/com/google/firebase/ThreadManager.java

@@ -32,8 +32,8 @@
  *
  * <p>Multiple app instances may use the same <code>ThreadManager</code> instance.
  * Methods in this interface may get invoked multiple times by the same
- * app, during its lifetime. Apps may also invoke methods of this interface concurrently, and
- * therefore implementations should provide any synchronization necessary.
+ * app, during its lifetime. Apps may also invoke methods of this interface concurrently and
+ * so implementations should provide any synchronization necessary.
  */
 public abstract class ThreadManager {
 
@@ -76,11 +76,11 @@ protected abstract void releaseExecutor(
    * Returns the <code>ThreadFactory</code> to be used for creating long-lived threads. This is
    * used mainly to create the long-lived worker threads for the Realtime Database client, and
    * other scheduled (periodic) tasks started by the SDK. The SDK guarantees
-   * clean termination of all threads started via this <code>ThreadFactory</code>, upon
-   * calling {@link FirebaseApp#delete()}.
+   * clean termination of all threads started via this <code>ThreadFactory</code>, when the user
+   * calls {@link FirebaseApp#delete()}.
    *
    * <p>If long-lived threads cannot be supported in the current runtime, this method may
-   * throw a RuntimeException.
+   * throw a {@code RuntimeException}.
    *
    * @return A non-null <code>ThreadFactory</code>.
    */

src/main/java/com/google/firebase/auth/FirebaseAuth.java

@@ -111,7 +111,7 @@ public static synchronized FirebaseAuth getInstance(FirebaseApp app) {
   }
 
   /**
-   * Similar to {@link #createCustomTokenAsync(String)}, but returns a Task.
+   * Similar to {@link #createCustomTokenAsync(String)}, but returns a {@link Task}.
    *
    * @param uid The UID to store in the token. This identifies the user to other Firebase services
    *     (Firebase Database, Firebase Auth, etc.)
@@ -124,7 +124,7 @@ public Task<String> createCustomToken(String uid) {
   }
 
   /**
-   * Similar to {@link #createCustomTokenAsync(String, Map)}, but returns a Task.
+   * Similar to {@link #createCustomTokenAsync(String, Map)}, but returns a {@link Task}.
    *
    * @param uid The UID to store in the token. This identifies the user to other Firebase services
    *     (Realtime Database, Storage, etc.). Should be less than 128 characters.
@@ -158,12 +158,14 @@ public String call() throws Exception {
 
   /**
    * Creates a Firebase Custom Token associated with the given UID. This token can then be provided
-   * back to a client application for use with the signInWithCustomToken authentication API.
+   * back to a client application for use with the
+   * <a href="/docs/auth/admin/create-custom-tokens#sign_in_using_custom_tokens_on_clients">signInWithCustomToken</a>
+   * authentication API.
    *
    * @param uid The UID to store in the token. This identifies the user to other Firebase services
-   *     (Firebase Database, Firebase Auth, etc.)
-   * @return An ApiFuture which will complete successfully with the created Firebase Custom Token,
-   *     or unsuccessfully with the failure Exception.
+   *     (Firebase Realtime Database, Firebase Auth, etc.)
+   * @return An {@code ApiFuture} which will complete successfully with the created Firebase Custom
+   *     Token, or unsuccessfully with the failure Exception.
    */
   public ApiFuture<String> createCustomTokenAsync(String uid) {
     return new TaskToApiFuture<>(createCustomToken(uid));
@@ -179,16 +181,16 @@ public ApiFuture<String> createCustomTokenAsync(String uid) {
    * @param developerClaims Additional claims to be stored in the token (and made available to
    *     security rules in Database, Storage, etc.). These must be able to be serialized to JSON
    *     (e.g. contain only Maps, Arrays, Strings, Booleans, Numbers, etc.)
-   * @return An ApiFuture which will complete successfully with the created Firebase Custom Token,
-   *     or unsuccessfully with the failure Exception.
+   * @return An {@code ApiFuture} which will complete successfully with the created Firebase Custom
+   *     Token, or unsuccessfully with the failure Exception.
    */
   public ApiFuture<String> createCustomTokenAsync(
       final String uid, final Map<String, Object> developerClaims) {
     return new TaskToApiFuture<>(createCustomToken(uid, developerClaims));
   }
 
   /**
-   * Similar to {@link #verifyIdTokenAsync(String)}, but returns a Task.
+   * Similar to {@link #verifyIdTokenAsync(String)}, but returns a {@link Task}.
    *
    * @param token A Firebase ID Token to verify and parse.
    * @return A {@link Task} which will complete successfully with the parsed token, or
@@ -235,20 +237,20 @@ public FirebaseToken call() throws Exception {
    * If the token is invalid, the future throws an exception indicating the failure.
    *
    * @param token A Firebase ID Token to verify and parse.
-   * @return An ApiFuture which will complete successfully with the parsed token, or
+   * @return An {@code ApiFuture} which will complete successfully with the parsed token, or
    *     unsuccessfully with the failure Exception.
    */
   public ApiFuture<FirebaseToken> verifyIdTokenAsync(final String token) {
     return new TaskToApiFuture<>(verifyIdToken(token));
   }
 
   /**
-   * Similar to {@link #getUserAsync(String)}, but returns a Task.
+   * Similar to {@link #getUserAsync(String)}, but returns a {@link Task}.
    *
    * @param uid A user ID string.
    * @return A {@link Task} which will complete successfully with a {@link UserRecord} instance.
    *     If an error occurs while retrieving user data or if the specified user ID does not exist,
-   *     the task fails with a FirebaseAuthException.
+   *     the task fails with a {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the user ID string is null or empty.
    * @deprecated Use {@link #getUserAsync(String)}
    */
@@ -267,22 +269,22 @@ public UserRecord call() throws Exception {
    * Gets the user data corresponding to the specified user ID.
    *
    * @param uid A user ID string.
-   * @return An ApiFuture which will complete successfully with a {@link UserRecord} instance.
-   *     If an error occurs while retrieving user data or if the specified user ID does not exist,
-   *     the future throws a FirebaseAuthException.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link UserRecord}
+   *     instance. If an error occurs while retrieving user data or if the specified user ID does
+   *     not exist, the future throws a {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the user ID string is null or empty.
    */
   public ApiFuture<UserRecord> getUserAsync(final String uid) {
     return new TaskToApiFuture<>(getUser(uid));
   }
 
   /**
-   * Similar to {@link #getUserByEmailAsync(String)}, but returns a Task.
+   * Similar to {@link #getUserByEmailAsync(String)}, but returns a {@link Task}.
    *
    * @param email A user email address string.
    * @return A {@link Task} which will complete successfully with a {@link UserRecord} instance.
    *     If an error occurs while retrieving user data or if the email address does not correspond
-   *     to a user, the task fails with a FirebaseAuthException.
+   *     to a user, the task fails with a {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the email is null or empty.
    * @deprecated Use {@link #getUserByEmailAsync(String)}
    */
@@ -301,22 +303,22 @@ public UserRecord call() throws Exception {
    * Gets the user data corresponding to the specified user email.
    *
    * @param email A user email address string.
-   * @return An ApiFuture which will complete successfully with a {@link UserRecord} instance.
-   *     If an error occurs while retrieving user data or if the email address does not correspond
-   *     to a user, the future throws a FirebaseAuthException.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link UserRecord}
+   *     instance. If an error occurs while retrieving user data or if the email address does not
+   *     correspond to a user, the future throws a {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the email is null or empty.
    */
   public ApiFuture<UserRecord> getUserByEmailAsync(final String email) {
     return new TaskToApiFuture<>(getUserByEmail(email));
   }
 
   /**
-   * Similar to {@link #getUserByPhoneNumberAsync(String)}, but returns a Task.
+   * Similar to {@link #getUserByPhoneNumberAsync(String)}, but returns a {@link Task}.
    *
    * @param phoneNumber A user phone number string.
    * @return A {@link Task} which will complete successfully with a {@link UserRecord} instance.
    *     If an error occurs while retrieving user data or if the phone number does not
-   *     correspond to a user, the task fails with a FirebaseAuthException.
+   *     correspond to a user, the task fails with a {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the phone number is null or empty.
    * @deprecated Use {@link #getUserByPhoneNumberAsync(String)}
    */
@@ -335,22 +337,22 @@ public UserRecord call() throws Exception {
    * Gets the user data corresponding to the specified user phone number.
    *
    * @param phoneNumber A user phone number string.
-   * @return An ApiFuture which will complete successfully with a {@link UserRecord} instance.
-   *     If an error occurs while retrieving user data or if the phone number does not
-   *     correspond to a user, the future throws a FirebaseAuthException.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link UserRecord}
+   *     instance. If an error occurs while retrieving user data or if the phone number does not
+   *     correspond to a user, the future throws a {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the phone number is null or empty.
    */
   public ApiFuture<UserRecord> getUserByPhoneNumberAsync(final String phoneNumber) {
     return new TaskToApiFuture<>(getUserByPhoneNumber(phoneNumber));
   }
 
   /**
-   * Similar to {@link #createUserAsync(CreateRequest)}, but returns a Task.
+   * Similar to {@link #createUserAsync(CreateRequest)}, but returns a {@link Task}.
    *
    * @param request A non-null {@link CreateRequest} instance.
    * @return A {@link Task} which will complete successfully with a {@link UserRecord} instance
    *     corresponding to the newly created account. If an error occurs while creating the user
-   *     account, the task fails with a FirebaseAuthException.
+   *     account, the task fails with a {@link FirebaseAuthException}.
    * @throws NullPointerException if the provided request is null.
    * @deprecated Use {@link #createUserAsync(CreateRequest)}
    */
@@ -371,22 +373,22 @@ public UserRecord call() throws Exception {
    * {@link CreateRequest}.
    *
    * @param request A non-null {@link CreateRequest} instance.
-   * @return An ApiFuture which will complete successfully with a {@link UserRecord} instance
-   *     corresponding to the newly created account. If an error occurs while creating the user
-   *     account, the future throws a FirebaseAuthException.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link UserRecord}
+   *     instance corresponding to the newly created account. If an error occurs while creating the
+   *     user account, the future throws a {@link FirebaseAuthException}.
    * @throws NullPointerException if the provided request is null.
    */
   public ApiFuture<UserRecord> createUserAsync(final CreateRequest request) {
     return new TaskToApiFuture<>(createUser(request));
   }
 
   /**
-   * Similar to {@link #updateUserAsync(UpdateRequest)}, but returns a Task.
+   * Similar to {@link #updateUserAsync(UpdateRequest)}, but returns a {@link Task}.
    *
    * @param request A non-null {@link UpdateRequest} instance.
    * @return A {@link Task} which will complete successfully with a {@link UserRecord} instance
    *     corresponding to the updated user account. If an error occurs while updating the user
-   *     account, the task fails with a FirebaseAuthException.
+   *     account, the task fails with a {@link FirebaseAuthException}.
    * @throws NullPointerException if the provided update request is null.
    * @deprecated Use {@link #updateUserAsync(UpdateRequest)}
    */
@@ -407,22 +409,22 @@ public UserRecord call() throws Exception {
    * {@link UpdateRequest}.
    *
    * @param request A non-null {@link UpdateRequest} instance.
-   * @return An ApiFuture which will complete successfully with a {@link UserRecord} instance
-   *     corresponding to the updated user account. If an error occurs while updating the user
-   *     account, the future throws a FirebaseAuthException.
+   * @return An {@code ApiFuture} which will complete successfully with a {@link UserRecord}
+   *     instance corresponding to the updated user account. If an error occurs while updating the
+   *     user account, the future throws a {@link FirebaseAuthException}.
    * @throws NullPointerException if the provided update request is null.
    */
   public ApiFuture<UserRecord> updateUserAsync(final UpdateRequest request) {
     return new TaskToApiFuture<>(updateUser(request));
   }
 
   /**
-   * Similar to {@link #deleteUserAsync(String)}, but returns a Task.
+   * Similar to {@link #deleteUserAsync(String)}, but returns a {@link Task}.
    *
    * @param uid A user ID string.
    * @return A {@link Task} which will complete successfully when the specified user account has
    *     been deleted. If an error occurs while deleting the user account, the task fails with a
-   *     FirebaseAuthException.
+   *     {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the user ID string is null or empty.
    * @deprecated Use {@link #deleteUserAsync(String)}
    */
@@ -455,9 +457,9 @@ private void destroy() {
    * Deletes the user identified by the specified user ID.
    *
    * @param uid A user ID string.
-   * @return An ApiFuture which will complete successfully when the specified user account has
-   *     been deleted. If an error occurs while deleting the user account, the future throws a
-   *     FirebaseAuthException.
+   * @return An {@code ApiFuture} which will complete successfully when the specified user account
+   *     has been deleted. If an error occurs while deleting the user account, the future throws a
+   *     {@link FirebaseAuthException}.
    * @throws IllegalArgumentException If the user ID string is null or empty.
    */
   public ApiFuture<Void> deleteUserAsync(final String uid) {