add coverage for introduced use cases and javadocs

auth0/src/main/java/com/auth0/android/provider/AuthenticationActivity.java

@@ -115,7 +115,7 @@ private void launchAuthenticationIntent() {
  }
 
  CustomTabsOptions customTabsOptions = extras.getParcelable(EXTRA_CT_OPTIONS);
- assert customTabsOptions != null;
+ //noinspection ConstantConditions
  customTabsController = createCustomTabsController(this, customTabsOptions);
  customTabsController.bindService();
  //noinspection ConstantConditions

auth0/src/main/java/com/auth0/android/provider/BrowserPicker.java

@@ -16,6 +16,10 @@
 
 import static android.support.customtabs.CustomTabsService.ACTION_CUSTOM_TABS_CONNECTION;
 
+/**
+ * Class used to match any browser, preferring Custom Tabs compatible browsers
+ * and browsers that are selected as the default browser application in the device settings.
+ */
 public class BrowserPicker implements Parcelable {
 
  @NonNull
@@ -59,7 +63,8 @@ public BrowserPicker[] newArray(int size) {
  };
 
  /**
- * Create a new BrowserPicker.Builder instance.
+ * Starts building a new BrowserPicker that will match any browser, preferring Custom Tabs compatible browsers
+ * and browsers that are selected as the default browser application in the device settings.
  *
  * @return a new BrowserPicker.Builder ready to customize.
  */
@@ -74,13 +79,27 @@ public static class Builder {
  private Builder() {
  }
 
- //TODO: JAVADOCS
+ /**
+ * Filters from the available browsers those whose package name is contained in the given list.
+ * The order of the list matters, as will be used as preference. Default browsers selected
+ * explicitly by the end-user in the device settings, will be always preferred when they are
+ * included in the allowed packages list.
+ *
+ * @param allowedPackages the list of browser package names to allow.
+ * @return this builder instance.
+ */
  @NonNull
  public Builder withAllowedPackages(@NonNull List<String> allowedPackages) {
  this.allowedPackages = allowedPackages;
  return this;
  }
 
+ /**
+ * Constructs a new BrowserPicker.
+ *
+ * @return a new BrowserPicker.
+ * @see CustomTabsOptions
+ */
  @NonNull
  public BrowserPicker build() {
  return new BrowserPicker(allowedPackages);
@@ -120,14 +139,7 @@ String getBestBrowserPackage(@NonNull PackageManager pm) {
 
  //If the browser packages were filtered, use the allowed packages list as order preference.
  //A user-selected default browser will always be picked up first.
- List<String> preferenceList = allowedPackages;
- if (!isFilterEnabled) {
- preferenceList = new ArrayList<>();
- if (defaultBrowser != null) {
- preferenceList.add(defaultBrowser);
- }
- preferenceList.addAll(CHROME_BROWSERS);
- }
+ List<String> preferenceList = getPreferenceOrder(allowedPackages, defaultBrowser);
 
  //If the list was filtered, the customTabsBrowsers and regularBrowsers Lists will contain only allowed packages.
  final String customTabBrowser = getFirstMatch(customTabsBrowsers, preferenceList, defaultBrowser);
@@ -140,6 +152,18 @@ String getBestBrowserPackage(@NonNull PackageManager pm) {
  return getFirstMatch(regularBrowsers, preferenceList, defaultBrowser);
  }
 
+ private List<String> getPreferenceOrder(@Nullable List<String> allowedPackages, @Nullable String defaultBrowser) {
+ if (allowedPackages != null) {
+ return allowedPackages;
+ }
+ List<String> preferenceList = new ArrayList<>();
+ if (defaultBrowser != null) {
+ preferenceList.add(defaultBrowser);
+ }
+ preferenceList.addAll(CHROME_BROWSERS);
+ return preferenceList;
+ }
+
  @Nullable
  private String getFirstMatch(@NonNull List<String> baseList, @NonNull List<String> preferenceList, @Nullable String bestChoice) {
  if (bestChoice != null && preferenceList.contains(bestChoice) && baseList.contains(bestChoice)) {

auth0/src/main/java/com/auth0/android/provider/CustomTabsOptions.java

@@ -13,6 +13,8 @@
 import android.support.customtabs.CustomTabsSession;
 import android.support.v4.content.ContextCompat;
 
+import com.auth0.android.authentication.AuthenticationException;
+
 /**
  * Holder for Custom Tabs customization options. Use {@link CustomTabsOptions#newBuilder()} to begin.
  */
@@ -142,6 +144,7 @@ public Builder showTitle(boolean showTitle) {
  *
  * @param browserPicker the browser picker to use.
  * @return the current builder instance
+ * @see AuthenticationException#isBrowserAppNotAvailable()
  */
  @NonNull
  public Builder withBrowserPicker(@NonNull BrowserPicker browserPicker) {

auth0/src/main/java/com/auth0/android/provider/WebAuthProvider.java

@@ -118,10 +118,12 @@ public LogoutBuilder withReturnToUrl(@NonNull String returnToUrl) {
  }
 
  /**
- * Request the user session to be cleared. When successful, the callback will get invoked
+ * Request the user session to be cleared. When successful, the callback will get invoked.
+ * An error is raised if there are no browser applications installed in the device.
  *
  * @param context to run the log out
  * @param callback to invoke when log out is successful
+ * @see AuthenticationException#isBrowserAppNotAvailable()
  */
  public void start(@NonNull Context context, @NonNull VoidCallback callback) {
  resetManagerInstance();
@@ -424,10 +426,12 @@ Builder withPKCE(@Nullable PKCE pkce) {
 
  /**
  * Request user Authentication. The result will be received in the callback.
+ * An error is raised if there are no browser applications installed in the device.
  *
  * @param activity context to run the authentication
  * @param callback to receive the parsed results
  * @param requestCode to use in the authentication request
+ * @see AuthenticationException#isBrowserAppNotAvailable()
  * @deprecated This method has been deprecated since it only applied to WebView authentication and Google is no longer supporting it. Please use {@link WebAuthProvider.Builder#start(Activity, AuthCallback)}
  */
  @SuppressLint("VisibleForTests")
@@ -458,9 +462,11 @@ public void start(@NonNull Activity activity, @NonNull AuthCallback callback, in
 
  /**
  * Request user Authentication. The result will be received in the callback.
+ * An error is raised if there are no browser applications installed in the device.
  *
  * @param activity context to run the authentication
  * @param callback to receive the parsed results
+ * @see AuthenticationException#isBrowserAppNotAvailable()
  */
  public void start(@NonNull Activity activity, @NonNull AuthCallback callback) {
  //noinspection deprecation