From 5368d76218b3cdd3fb52b76e27ceacedee5ec51f Mon Sep 17 00:00:00 2001
From: Anthony Restaino <anthonyrestaino11@gmail.com>
Date: Sun, 17 Jan 2016 23:45:12 -0500
Subject: [PATCH] Documentation for Utils class

---
 .../acr/browser/lightning/utils/Utils.java    | 66 ++++++++++++++++---
 1 file changed, 58 insertions(+), 8 deletions(-)

diff --git a/app/src/main/java/acr/browser/lightning/utils/Utils.java b/app/src/main/java/acr/browser/lightning/utils/Utils.java
index 7681877..86e3d9e 100644
--- a/app/src/main/java/acr/browser/lightning/utils/Utils.java
+++ b/app/src/main/java/acr/browser/lightning/utils/Utils.java
@@ -22,6 +22,7 @@ import android.graphics.Path;
 import android.graphics.Shader;
 import android.os.Environment;
 import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
 import android.support.annotation.StringRes;
 import android.support.design.widget.Snackbar;
 import android.support.v7.app.AlertDialog;
@@ -47,6 +48,16 @@ import acr.browser.lightning.download.DownloadHandler;
 
 public final class Utils {
 
+    /**
+     * Downloads a file from the specified URL. Handles permissions
+     * requests, and creates all the necessary dialogs that must be
+     * showed to the user.
+     *
+     * @param activity           activity needed to created dialogs.
+     * @param url                url to download from.
+     * @param userAgent          the user agent of the browser.
+     * @param contentDisposition the content description of the file.
+     */
     public static void downloadFile(final Activity activity, final String url,
                                     final String userAgent, final String contentDisposition) {
         PermissionsManager.getInstance().requestPermissionsIfNecessaryForResult(activity, new String[]{Manifest.permission.READ_EXTERNAL_STORAGE,
@@ -67,6 +78,18 @@ public final class Utils {
 
     }
 
+    /**
+     * Creates a new intent that can launch the email
+     * app with a subject, address, body, and cc. It
+     * is used to handle mail:to links.
+     *
+     * @param address the address to send the email to.
+     * @param subject the subject of the email.
+     * @param body    the body of the email.
+     * @param cc      extra addresses to CC.
+     * @return a valid intent.
+     */
+    @NonNull
     public static Intent newEmailIntent(String address, String subject,
                                         String body, String cc) {
         Intent intent = new Intent(Intent.ACTION_SEND);
@@ -78,12 +101,19 @@ public final class Utils {
         return intent;
     }
 
-    public static void createInformativeDialog(Context context, @StringRes int title, @StringRes int message) {
-        AlertDialog.Builder builder = new AlertDialog.Builder(context);
+    /**
+     * Creates a dialog with only a title, message, and okay button.
+     *
+     * @param activity the activity needed to create a dialog.
+     * @param title    the title of the dialog.
+     * @param message  the message of the dialog.
+     */
+    public static void createInformativeDialog(Activity activity, @StringRes int title, @StringRes int message) {
+        AlertDialog.Builder builder = new AlertDialog.Builder(activity);
         builder.setTitle(title);
         builder.setMessage(message)
                 .setCancelable(true)
-                .setPositiveButton(context.getResources().getString(R.string.action_ok),
+                .setPositiveButton(activity.getResources().getString(R.string.action_ok),
                         new DialogInterface.OnClickListener() {
                             @Override
                             public void onClick(DialogInterface dialog, int id) {
@@ -93,30 +123,50 @@ public final class Utils {
         alert.show();
     }
 
+    /**
+     * Displays a snackbar to the user with a String resource.
+     *
+     * @param activity the activity needed to create a snackbar.
+     * @param resource the string resource to show to the user.
+     */
     public static void showSnackbar(@NonNull Activity activity, @StringRes int resource) {
         View view = activity.findViewById(android.R.id.content);
         if (view == null) return;
         Snackbar.make(view, resource, Snackbar.LENGTH_SHORT).show();
     }
 
-    public static void showSnackbar(@NonNull Activity activity, String message) {
+    /**
+     * Displays a snackbar to the user with a string message.
+     *
+     * @param activity the activity needed to create a snackbar.
+     * @param message  the string message to show to the user.
+     */
+    public static void showSnackbar(@NonNull Activity activity, @NonNull String message) {
         View view = activity.findViewById(android.R.id.content);
         if (view == null) return;
         Snackbar.make(view, message, Snackbar.LENGTH_SHORT).show();
     }
 
     /**
-     * Converts Density Pixels (DP) to Pixels (PX)
+     * Converts Density Pixels (DP) to Pixels (PX).
      *
-     * @param dp the number of density pixels to convert
-     * @return the number of pixels
+     * @param dp the number of density pixels to convert.
+     * @return the number of pixels that the conversion generates.
      */
     public static int dpToPx(int dp) {
         DisplayMetrics metrics = Resources.getSystem().getDisplayMetrics();
         return (int) (dp * metrics.density + 0.5f);
     }
 
-    public static String getDomainName(String url) {
+    /**
+     * Extracts the domain name from a URL.
+     *
+     * @param url the URL to extract the domain from.
+     * @return the domain name, or the URL if the domain
+     * could not be extracted. The domain name may include
+     * HTTPS if the URL is an SSL supported URL.
+     */
+    public static String getDomainName(@Nullable String url) {
         if (url == null || url.isEmpty()) return "";
 
         boolean ssl = url.startsWith(Constants.HTTPS);