Remove in-depth documentation for AuthUI.java and link to README instead (#569)

Author: SUPERCILEX

auth/README.md

@@ -29,7 +29,7 @@ and [Web](https://github.com/firebase/firebaseui-web/).
 
 ![FirebaseUI authentication demo on Android](demo.gif)
 
-## Table of Content
+## Table of Contents
 
 1. [Configuration](#configuration)
 2. [Usage instructions](#using-firebaseui-for-authentication)

auth/src/main/java/com/firebase/ui/auth/AuthUI.java

@@ -60,173 +60,14 @@
 import java.util.Set;
 
 /**
- * The entry point to the AuthUI authentication flow, and related utility methods.
- * If your application uses the default {@link FirebaseApp} instance, an AuthUI instance can
- * be retrieved simply by calling {@link AuthUI#getInstance() AuthUI.getInstance()}.
- * If an alternative app instance is in use, call
- * {@link AuthUI#getInstance(FirebaseApp) AuthUI.getInstance(app} instead, passing the
- * appropriate app instance.
+ * The entry point to the AuthUI authentication flow, and related utility methods. If your
+ * application uses the default {@link FirebaseApp} instance, an AuthUI instance can be retrieved
+ * simply by calling {@link AuthUI#getInstance()}. If an alternative app instance is in use, call
+ * {@link AuthUI#getInstance(FirebaseApp)} instead, passing the appropriate app instance.
  * <p>
- * <h2>Sign-in</h2>
  * <p>
- * If a user is not currently signed in (as can be determined by checking
- * {@code auth.getCurrentUser() != null}, where {@code auth} is the {@link FirebaseAuth}
- * associated with your {@link FirebaseApp}) then the sign-in process can be started by creating
- * a sign-in intent using {@link SignInIntentBuilder}. A builder instance can be retrieved by
- * calling {@link AuthUI#createSignInIntentBuilder()}.
- * <p>
- * <p>The builder provides the following customization options for the authentication flow
- * implemented by this library:
- * <p>
- * <ul>
- *     <li>The set of authentication methods desired can be specified.</li>
- *     <li>The terms of service URL for your app can be specified, which is included as a link
- *         in the small-print of the account creation step for new users. If no terms of service
- *         URL is provided, the associated small-print is omitted.
- *     </li>
- *     <li>A custom theme can specified for the flow, which is applied to all the activities in
- *         the flow for consistent customization of colors and typography.
- *     </li>
- * </ul>
- * <p>
- * <p>
- * <h3>Sign-in examples</h3>
- * <p>
- * If no customization is required, and only email authentication is required, the sign-in flow
- * can be started as follows:
- * <p>
- * <pre>
- * {@code
- * startActivityForResult(
- *     AuthUI.getInstance().createSignInIntentBuilder().build(),
- *     RC_SIGN_IN);
- * }
- * </pre>
- * <p>
- * If Google Sign-in and Facebook Sign-in are also required, then this can be replaced with:
- * <p>
- * <pre>
- * {@code
- * startActivityForResult(
- *     AuthUI.getInstance()
- *         .createSignInIntentBuilder()
- *         .setProviders(
- *              Arrays.asList(
- *                  new IdpConfig.Builder(AuthUI.EMAIL_PROVIDER).build(),
- *                  new IdpConfig.Builder(AuthUI.GOOGLE_PROVIDER).build(),
- *                  new IdpConfig.Builder(AuthUI.FACEBOOK_PROVIDER).build()
- *              )
- *         )
- *         .build(),
- *     RC_SIGN_IN);
- * }
- * </pre>
- * <p>
- * Finally, if a terms of service URL and a custom theme are required:
- * <p>
- * <pre>
- * {@code
- * startActivityForResult(
- *     AuthUI.getInstance()
- *         .createSignInIntentBuilder()
- *         .setProviders(...)
- *         .setTosUrl("https://superapp.example.com/terms-of-service.html")
- *         .setTheme(R.style.SuperAppTheme)
- *         .build(),
- *     RC_SIGN_IN);
- * }
- * </pre>
- * <p>
- * <h3>Handling the Sign-in response</h3>
- * <p>
- * The authentication flow provides only two response codes:
- * {@link ResultCodes#OK RESULT_OK} if a user is signed in,
- * and {@link ResultCodes#CANCELED RESULT_CANCELLED} if sign in
- * failed. No further information on failure is provided as it is not typically useful; the only
- * recourse for most apps if sign in fails is to ask the user to sign in again later, or proceed
- * with an anonymous account if supported.
- * <p>
- * <pre>
- * {@code
- * @Override
- * protected void onActivityResult(int requestCode, int resultCode, Intent data) {
- *   super.onActivityResult(requestCode, resultCode, data);
- *   if (requestCode == RC_SIGN_IN) {
- *     if (resultCode == ResultCodes.OK) {
- *       // user is signed in!
- *       startActivity(new Intent(this, WelcomeBackActivity.class));
- *       finish();
- *     } else {
- *       // user is not signed in :(
- *       // Maybe just wait for the user to press "sign in" again, or show a message
- *       showSnackbar("Sign in is required to use this app.");
- *     }
- *   }
- * }
- * </pre>
- * <p>
- * <h2>Sign-out</h2>
- * <p>
- * With the integrations provided by AuthUI, signing out a user is a multi-stage process:
- * <p>
- * <ol>
- *     <li>The user must be signed out of the {@link FirebaseAuth} instance.</li>
- *     <li>Smart Lock for Passwords must be instructed to disable automatic sign-in, in
- *         order to prevent an automatic sign-in loop that prevents the user from switching
- *         accounts.
- *     </li>
- *     <li>If the current user signed in using either Google or Facebook, the user must also be
- *         signed out using the associated API for that authentication method. This typically
- *         ensures that the user will not be automatically signed-in using the current account
- *         when using that authentication method again from the authentication method picker, which
- *         would also prevent the user from switching between accounts on the same provider.
- *     </li>
- * </ol>
- * <p>
- * In order to make this process easier, AuthUI provides a simple
- * {@link AuthUI#signOut(Activity) signOut} method to encapsulate this behavior. The method returns
- * a {@link Task} which is marked completed once all necessary sign-out operations are completed:
- * <p>
- * <pre>
- * {@code
- * public void onClick(View v) {
- *   if (v.getId() == R.id.sign_out) {
- *       AuthUI.getInstance()
- *           .signOut(this)
- *           .addOnCompleteListener(new OnCompleteListener<AuthResult>() {
- *             public void onComplete(@NonNull Task<AuthResult> task) {
- *               // user is now signed out
- *               startActivity(new Intent(MyActivity.this, SignInActivity.class));
- *               finish();
- *             });
- *   }
- * }
- * </pre>
- * <p>
- * <h2>IDP Provider configuration</h2>
- * <p>
- * Interacting with identity providers typically requires some additional client configuration.
- * AuthUI currently supports Google Sign-in and Facebook Sign-in, and currently requires the
- * basic configuration for these providers to be specified via string properties:
- * <p>
- * <ul>
- * <p>
- * <li>Google Sign-in: If your app build uses the
- * <a href="https://developers.google.com/android/guides/google-services-plugin">Google
- * Services Gradle Plugin</a>, no additional configuration is required. If not, please override
- * {@code R.string.default_web_client_id} to provide your
- * <a href="https://developers.google.com/identity/sign-in/web/devconsole-project">Google OAuth
- * web client id.</a>
- * </li>
- * <p>
- * <li>Facebook Sign-in: Please override the string resource
- * {@code facebook_application_id} to provide the
- * <a href="https://developers.facebook.com/docs/apps/register">App ID</a> for your app as
- * registered on the
- * <a href="https://developers.facebook.com/apps">Facebook Developer Dashboard</a>.
- * </li>
- * <p>
- * </ul>
+ * See the <a href="https://github.com/firebase/FirebaseUI-Android/blob/master/auth/README.md#table-of-contents">README</a>
+ * for examples on how to get started with FirebaseUI Auth.
  */
 public class AuthUI {
 
@@ -252,8 +93,7 @@ public class AuthUI {
     public static final String TWITTER_PROVIDER = TwitterAuthProvider.PROVIDER_ID;
 
     /**
-     * Default value for logo resource, omits the logo from the
-     * {@link AuthMethodPickerActivity}
+     * Default value for logo resource, omits the logo from the {@link AuthMethodPickerActivity}.
      */
     public static final int NO_LOGO = -1;
 
@@ -304,8 +144,8 @@ public static AuthUI getInstance(FirebaseApp app) {
     }
 
     /**
-     * Default theme used by {@link SignInIntentBuilder#setTheme(int)} if no theme
-     * customization is required.
+     * Default theme used by {@link SignInIntentBuilder#setTheme(int)} if no theme customization is
+     * required.
      */
     @StyleRes
     public static int getDefaultTheme() {
@@ -524,9 +364,9 @@ public static class Builder {
             /**
              * Builds the configuration parameters for an identity provider.
              *
-             * @param providerId An ID of one of the supported identity providers. e.g.
-             *                   {@link AuthUI#GOOGLE_PROVIDER}. See {@link AuthUI#SUPPORTED_PROVIDERS} for the
-             *                   complete list of supported Identity providers
+             * @param providerId An ID of one of the supported identity providers. e.g. {@link
+             *                   AuthUI#GOOGLE_PROVIDER}. See {@link AuthUI#SUPPORTED_PROVIDERS} for
+             *                   the complete list of supported Identity providers
              */
             public Builder(@NonNull String providerId) {
                 if (!SUPPORTED_PROVIDERS.contains(providerId)) {
@@ -546,7 +386,8 @@ public Builder(@NonNull String providerId) {
              * For Google permissions see:
              * https://developers.google.com/identity/protocols/googlescopes
              * <p>
-             * Twitter permissions are only configurable through the Twitter developer console.
+             * Twitter permissions are only configurable through the
+             * <a href="https://apps.twitter.com/">Twitter developer console</a>.
              */
             public Builder setPermissions(List<String> permissions) {
                 mScopes = permissions;