Doc cleanup and more extensive coverage of API entry point

Iain McGinniss · Iain McGinniss · commit 24382846156b · 2016-05-14T19:47:59.000-07:00
Change-Id: I65b90b97487a6f82489d7a8ec9ec52ab28009154
diff --git a/auth/build.gradle b/auth/build.gradle
@@ -42,3 +42,7 @@ task checkAllSource(type: Checkstyle) {
     include '**/*.java'
     classpath = files(project.configurations.compile)
 }
+
+javadoc.exclude 'com/firebase/ui/auth/provider/**'
+javadoc.exclude 'com/firebase/ui/auth/util/**'
+javadoc.exclude 'com/firebase/ui/auth/ui/email/field_validators/**'
diff --git a/auth/src/main/AndroidManifest.xml b/auth/src/main/AndroidManifest.xml
@@ -30,7 +30,7 @@
                   android:name="com.firebase.ui.auth.ui.idp.IDPSignInContainerActivity" >
         </activity>
         <activity android:theme="@style/FirebaseUI.Translucent"
-                   android:name="com.firebase.ui.auth.ui.credentials.ChooseAccountActivity" >
+                   android:name=".ui.ChooseAccountActivity" >
         </activity>
         <activity android:theme="@style/FirebaseUI.Translucent"
                   android:name="com.facebook.FacebookActivity"
diff --git a/auth/src/main/java/com/firebase/ui/auth/AuthUI.java b/auth/src/main/java/com/firebase/ui/auth/AuthUI.java
@@ -26,7 +26,7 @@
 import com.firebase.ui.auth.provider.GoogleProvider;
 import com.firebase.ui.auth.provider.IDPProviderParcel;
 import com.firebase.ui.auth.ui.FlowParameters;
-import com.firebase.ui.auth.ui.credentials.ChooseAccountActivity;
+import com.firebase.ui.auth.ui.ChooseAccountActivity;
 import com.firebase.ui.auth.util.CredentialsApiHelper;
 import com.firebase.ui.auth.util.Preconditions;
 import com.google.android.gms.common.api.Status;
diff --git a/auth/src/main/java/com/firebase/ui/auth/package-info.java b/auth/src/main/java/com/firebase/ui/auth/package-info.java
@@ -13,6 +13,7 @@
  */
 
 /**
- * TODO: javadoc
+ * The Firebase AuthUI library. See the {@link com.firebase.ui.auth.AuthUI} entry class
+ * for information on using the library to manage signed-in user state.
  */
 package com.firebase.ui.auth;
diff --git a/auth/src/main/java/com/firebase/ui/auth/provider/package-info.java b/auth/src/main/java/com/firebase/ui/auth/provider/package-info.java
@@ -0,0 +1,19 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the
+ * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * IDP-specific interactions for signing in users. The contents of this package should
+ * be considered an implementation detail and not part of the main API.
+ */
+package com.firebase.ui.auth.provider;
diff --git a/auth/src/main/java/com/firebase/ui/auth/ui/ChooseAccountActivity.java b/auth/src/main/java/com/firebase/ui/auth/ui/ChooseAccountActivity.java
@@ -12,7 +12,7 @@
  * limitations under the License.
  */
 
-package com.firebase.ui.auth.ui.credentials;
+package com.firebase.ui.auth.ui;
 
 import android.app.Activity;
 import android.content.Context;
@@ -23,11 +23,7 @@
 
 import com.firebase.ui.auth.BuildConfig;
 import com.firebase.ui.auth.provider.IDPProviderParcel;
-import com.firebase.ui.auth.ui.ActivityBase;
-import com.firebase.ui.auth.ui.ActivityHelper;
-import com.firebase.ui.auth.ui.FlowParameters;
 import com.firebase.ui.auth.ui.email.EmailHintContainerActivity;
-import com.firebase.ui.auth.ui.email.SignInNoPasswordActivity;
 import com.firebase.ui.auth.ui.idp.AuthMethodPickerActivity;
 import com.firebase.ui.auth.ui.idp.IDPSignInContainerActivity;
 import com.firebase.ui.auth.util.CredentialsAPI;
diff --git a/auth/src/main/java/com/firebase/ui/auth/ui/account_link/package-info.java b/auth/src/main/java/com/firebase/ui/auth/ui/account_link/package-info.java
@@ -0,0 +1,18 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the
+ * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Activities related to linking a new authentication method to an existing account.
+ */
+package com.firebase.ui.auth.ui.account_link;
diff --git a/auth/src/main/java/com/firebase/ui/auth/ui/email/field_validators/package-info.java b/auth/src/main/java/com/firebase/ui/auth/ui/email/field_validators/package-info.java
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the
+ * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Contains utility classes for validating {@link android.widget.EditText} field contents.
+ * The contents of this package should be considered an implementation detail and not part of
+ * the main API.
+ */
+package com.firebase.ui.auth.ui.email.field_validators;
diff --git a/auth/src/main/java/com/firebase/ui/auth/ui/email/package-info.java b/auth/src/main/java/com/firebase/ui/auth/ui/email/package-info.java
@@ -0,0 +1,18 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the
+ * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Activities related to the email and password based authentication.
+ */
+package com.firebase.ui.auth.ui.email;
diff --git a/auth/src/main/java/com/firebase/ui/auth/ui/idp/package-info.java b/auth/src/main/java/com/firebase/ui/auth/ui/idp/package-info.java
@@ -0,0 +1,18 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the
+ * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Activites related to identity provider authentication.
+ */
+package com.firebase.ui.auth.ui.idp;
diff --git a/auth/src/main/java/com/firebase/ui/auth/ui/package-info.java b/auth/src/main/java/com/firebase/ui/auth/ui/package-info.java
@@ -0,0 +1,18 @@
+/*
+ * Copyright 2016 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the
+ * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Activities which implement the AuthUI authentication flow.
+ */
+package com.firebase.ui.auth.ui;
diff --git a/auth/src/main/java/com/firebase/ui/auth/util/Preconditions.java b/auth/src/main/java/com/firebase/ui/auth/util/Preconditions.java
@@ -10,8 +10,8 @@
 public final class Preconditions {
 
     /**
-     * Ensures that the provided value is not null, and throws a {@link NullPointerException} if
-     * it is with a message constructed from the provided error template and arguments.
+     * Ensures that the provided value is not null, and throws a {@link NullPointerException}
+     * if it is null, with a message constructed from the provided error template and arguments.
      */
     public static <T> T checkNotNull(
             T val,
@@ -23,6 +23,11 @@ public static <T> T checkNotNull(
         return val;
     }
 
+    /**
+     * Ensures that the provided identifier matches a known style resource, and throws
+     * an {@link IllegalArgumentException} if the resource cannot be found, or is not
+     * a style resource, with a message constructed from the provided error template and arguments.
+     */
     @StyleRes
     public static int checkValidStyle(
             Context context,
diff --git a/auth/src/main/java/com/firebase/ui/auth/util/package-info.java b/auth/src/main/java/com/firebase/ui/auth/util/package-info.java
@@ -13,6 +13,8 @@
  */
 
 /**
- * TODO: javadoc
+ * Utilities to simplify interactions with {@code GoogleApiClient} and the APIs it provides,
+ * such as Google Sign-in and Smart Lock for Passwords. The contents of this package should
+ * be considered an implementation detail and not part of the main API.
  */
 package com.firebase.ui.auth.util;

Original file line number	Diff line number	Diff line change
`@@ -42,3 +42,7 @@ task checkAllSource(type: Checkstyle) {`
`42`	`42`	`include '*/.java'`
`43`	`43`	`classpath = files(project.configurations.compile)`
`44`	`44`	`}`
	`45`	`+`
	`46`	`+javadoc.exclude 'com/firebase/ui/auth/provider/**'`
	`47`	`+javadoc.exclude 'com/firebase/ui/auth/util/**'`
	`48`	`+javadoc.exclude 'com/firebase/ui/auth/ui/email/field_validators/**'`