diff --git a/WordPressUtils/build.gradle b/WordPressUtils/build.gradle index 91e40a80530d..e0ef2731bb57 100644 --- a/WordPressUtils/build.gradle +++ b/WordPressUtils/build.gradle @@ -91,3 +91,17 @@ uploadArchives { } } } + +android.libraryVariants.all { variant -> + + task("generate${variant.name}Javadoc", type: Javadoc) { + description "Generates Javadoc for $variant.name." + source = variant.javaCompile.source + classpath = files(variant.javaCompile.classpath.files, android.getBootClasspath()) + + options { + links "http://docs.oracle.com/javase/7/docs/api/" + } + exclude '**/R.java' + } +} diff --git a/WordPressUtils/src/main/java/org/wordpress/android/util/AlertUtils.java b/WordPressUtils/src/main/java/org/wordpress/android/util/AlertUtils.java index 6dd5ed993e45..79b2dbcedaa7 100644 --- a/WordPressUtils/src/main/java/org/wordpress/android/util/AlertUtils.java +++ b/WordPressUtils/src/main/java/org/wordpress/android/util/AlertUtils.java @@ -30,10 +30,10 @@ public class AlertUtils { */ public static void showAlert(Context context, int titleId, int messageId) { Dialog dlg = new AlertDialog.Builder(context) - .setTitle(titleId) - .setPositiveButton(android.R.string.ok, null) - .setMessage(messageId) - .create(); + .setTitle(titleId) + .setPositiveButton(android.R.string.ok, null) + .setMessage(messageId) + .create(); dlg.show(); } @@ -42,14 +42,14 @@ public static void showAlert(Context context, int titleId, int messageId) { * Show Alert Dialog * @param context * @param titleId - * @param messageId + * @param message */ public static void showAlert(Context context, int titleId, String message) { Dialog dlg = new AlertDialog.Builder(context) - .setTitle(titleId) - .setPositiveButton(android.R.string.ok, null) - .setMessage(message) - .create(); + .setTitle(titleId) + .setPositiveButton(android.R.string.ok, null) + .setMessage(message) + .create(); dlg.show(); } @@ -65,15 +65,15 @@ public static void showAlert(Context context, int titleId, String message) { * @param negativeListener */ public static void showAlert(Context context, int titleId, int messageId, - CharSequence positiveButtontxt, DialogInterface.OnClickListener positiveListener, - CharSequence negativeButtontxt, DialogInterface.OnClickListener negativeListener) { + CharSequence positiveButtontxt, DialogInterface.OnClickListener positiveListener, + CharSequence negativeButtontxt, DialogInterface.OnClickListener negativeListener) { Dialog dlg = new AlertDialog.Builder(context) - .setTitle(titleId) - .setPositiveButton(positiveButtontxt, positiveListener) - .setNegativeButton(negativeButtontxt, negativeListener) - .setMessage(messageId) - .setCancelable(false) - .create(); + .setTitle(titleId) + .setPositiveButton(positiveButtontxt, positiveListener) + .setNegativeButton(negativeButtontxt, negativeListener) + .setMessage(messageId) + .setCancelable(false) + .create(); dlg.show(); } @@ -82,20 +82,19 @@ public static void showAlert(Context context, int titleId, int messageId, * Show Alert Dialog * @param context * @param titleId - * @param messageId + * @param message * @param positiveButtontxt * @param positiveListener */ public static void showAlert(Context context, int titleId, String message, - CharSequence positiveButtontxt, DialogInterface.OnClickListener positiveListener) { + CharSequence positiveButtontxt, DialogInterface.OnClickListener positiveListener) { Dialog dlg = new AlertDialog.Builder(context) - .setTitle(titleId) - .setPositiveButton(positiveButtontxt, positiveListener) - .setMessage(message) - .setCancelable(false) - .create(); + .setTitle(titleId) + .setPositiveButton(positiveButtontxt, positiveListener) + .setMessage(message) + .setCancelable(false) + .create(); dlg.show(); } -} - +} \ No newline at end of file diff --git a/WordPressUtils/src/main/java/org/wordpress/android/util/AppLog.java b/WordPressUtils/src/main/java/org/wordpress/android/util/AppLog.java index 724b4ec08540..71242e1e805f 100644 --- a/WordPressUtils/src/main/java/org/wordpress/android/util/AppLog.java +++ b/WordPressUtils/src/main/java/org/wordpress/android/util/AppLog.java @@ -11,7 +11,7 @@ import java.util.NoSuchElementException; /** - * simple wrapper for Android log calls, enables recording & displaying log + * simple wrapper for Android log calls, enables recording and displaying log */ public class AppLog { // T for Tag @@ -26,43 +26,81 @@ private AppLog() { throw new AssertionError(); } - /* - * defaults to false, pass true to capture log so it can be displayed by AppLogViewerActivity + /** + * Capture log so it can be displayed by AppLogViewerActivity + * @param enable A boolean flag to capture log. Default is false, pass true to enable recording */ public static void enableRecording(boolean enable) { mEnableRecording = enable; } + /** + * Sends a VERBOSE log message + * @param tag Used to identify the source of a log message. + * It usually identifies the class or activity where the log call occurs. + * @param message The message you would like logged. + */ public static void v(T tag, String message) { message = StringUtils.notNullStr(message); Log.v(TAG + "-" + tag.toString(), message); addEntry(tag, LogLevel.v, message); } + /** + * Sends a DEBUG log message + * @param tag Used to identify the source of a log message. + * It usually identifies the class or activity where the log call occurs. + * @param message The message you would like logged. + */ public static void d(T tag, String message) { message = StringUtils.notNullStr(message); Log.d(TAG + "-" + tag.toString(), message); addEntry(tag, LogLevel.d, message); } + /** + * Sends a INFO log message + * @param tag Used to identify the source of a log message. + * It usually identifies the class or activity where the log call occurs. + * @param message The message you would like logged. + */ public static void i(T tag, String message) { message = StringUtils.notNullStr(message); Log.i(TAG + "-" + tag.toString(), message); addEntry(tag, LogLevel.i, message); } + /** + * Sends a WARN log message + * @param tag Used to identify the source of a log message. + * It usually identifies the class or activity where the log call occurs. + * @param message The message you would like logged. + */ public static void w(T tag, String message) { message = StringUtils.notNullStr(message); Log.w(TAG + "-" + tag.toString(), message); addEntry(tag, LogLevel.w, message); } + /** + * Sends a ERROR log message + * @param tag Used to identify the source of a log message. + * It usually identifies the class or activity where the log call occurs. + * @param message The message you would like logged. + */ public static void e(T tag, String message) { message = StringUtils.notNullStr(message); Log.e(TAG + "-" + tag.toString(), message); addEntry(tag, LogLevel.e, message); } + /** + * Send a ERROR log message and log the exception. + * @param tag Used to identify the source of a log message. + * It usually identifies the class or activity where the log call occurs. + * @param message The message you would like logged. + * @param tr An exception to log + */ public static void e(T tag, String message, Throwable tr) { message = StringUtils.notNullStr(message); Log.e(TAG + "-" + tag.toString(), message, tr); @@ -70,12 +108,23 @@ public static void e(T tag, String message, Throwable tr) { addEntry(tag, LogLevel.e, "StackTrace: " + getStringStackTrace(tr)); } + /** + * Sends a ERROR log message and the exception with StackTrace + * @param tag Used to identify the source of a log message. It usually identifies the class or activity where the log call occurs. + * @param tr An exception to log to get StackTrace + */ public static void e(T tag, Throwable tr) { Log.e(TAG + "-" + tag.toString(), tr.getMessage(), tr); addEntry(tag, LogLevel.e, tr.getMessage()); addEntry(tag, LogLevel.e, "StackTrace: " + getStringStackTrace(tr)); } + /** + * Sends a ERROR log message + * @param tag Used to identify the source of a log message. It usually identifies the class or activity where the log call occurs. + * @param volleyErrorMsg + * @param statusCode + */ public static void e(T tag, String volleyErrorMsg, int statusCode) { if (TextUtils.isEmpty(volleyErrorMsg)) { return; @@ -178,8 +227,10 @@ private static String getStringStackTrace(Throwable throwable) { return errors.toString(); } - /* - * returns entire log as html for display (see AppLogViewerActivity) + /** + * Returns entire log as html for display (see AppLogViewerActivity) + * @param context + * @return Arraylist of Strings containing log messages */ public static ArrayList toHtmlList(Context context) { ArrayList items = new ArrayList(); @@ -195,24 +246,26 @@ public static ArrayList toHtmlList(Context context) { return items; } - /* - * returns entire log as plain text + /** + * Converts the entire log to plain text + * @param context + * @return The log as plain text */ public static String toPlainText(Context context) { StringBuilder sb = new StringBuilder(); // add version & device info sb.append("WordPress Android version: " + PackageUtils.getVersionName(context)).append("\n") - .append("Android device name: " + DeviceUtils.getInstance().getDeviceName(context)).append("\n\n"); + .append("Android device name: " + DeviceUtils.getInstance().getDeviceName(context)).append("\n\n"); Iterator it = mLogEntries.iterator(); int lineNum = 1; while (it.hasNext()) { - sb.append(String.format("%02d - ", lineNum)) - .append(it.next().mLogText) - .append("\n"); + sb.append(String.format("%02d - ", lineNum)) + .append(it.next().mLogText) + .append("\n"); lineNum++; } return sb.toString(); } -} +} \ No newline at end of file diff --git a/WordPressUtils/src/main/java/org/wordpress/android/util/HtmlUtils.java b/WordPressUtils/src/main/java/org/wordpress/android/util/HtmlUtils.java index 41d79cd735df..b5319372a234 100644 --- a/WordPressUtils/src/main/java/org/wordpress/android/util/HtmlUtils.java +++ b/WordPressUtils/src/main/java/org/wordpress/android/util/HtmlUtils.java @@ -15,9 +15,12 @@ import org.wordpress.android.util.helpers.WPQuoteSpan; public class HtmlUtils { - /* - * removes html from the passed string - relies on Html.fromHtml which handles invalid HTML, + + /** + * Removes html from the passed string - relies on Html.fromHtml which handles invalid HTML, * but it's very slow, so avoid using this where performance is important + * @param text String containing html + * @return String without HTML */ public static String stripHtml(final String text) { if (TextUtils.isEmpty(text)) { @@ -26,9 +29,11 @@ public static String stripHtml(final String text) { return Html.fromHtml(text).toString().trim(); } - /* - * this is much faster than stripHtml() but should only be used when we know the html is valid + /** + * This is much faster than stripHtml() but should only be used when we know the html is valid * since the regex will be unpredictable with invalid html + * @param str String containing only valid html + * @return String without HTML */ public static String fastStripHtml(String str) { if (TextUtils.isEmpty(str)) { @@ -50,7 +55,7 @@ public static String fastStripHtml(String str) { } /* - * same as apache.commons.lang.StringUtils.stripStart() but also removes non-breaking + * Same as apache.commons.lang.StringUtils.stripStart() but also removes non-breaking * space (160) chars */ private static String trimStart(final String str) { @@ -65,8 +70,10 @@ private static String trimStart(final String str) { return str.substring(start); } - /* - * convert html entities to actual Unicode characters - relies on commons apache lang + /** + * Convert html entities to actual Unicode characters - relies on commons apache lang + * @param text String to be decoded to Unicode + * @return String containing unicode characters */ public static String fastUnescapeHtml(final String text) { if (text == null || !text.contains("&")) { @@ -75,8 +82,11 @@ public static String fastUnescapeHtml(final String text) { return StringEscapeUtils.unescapeHtml(text); } - /* - * converts an R.color.xxx resource to an HTML hex color + /** + * Converts an R.color.xxx resource to an HTML hex color + * @param context Android Context + * @param resId Android R.color.xxx + * @return A String HTML hex color code */ public static String colorResToHtmlColor(Context context, int resId) { try { @@ -86,12 +96,14 @@ public static String colorResToHtmlColor(Context context, int resId) { } } - /* - * remove blocks from the passed string - added to project after noticing + /** + * Remove {@code } blocks from the passed string - added to project after noticing * comments on posts that use the "Sociable" plugin ( http://wordpress.org/plugins/sociable/ ) - * may have a script block which contains followed by a CDATA section followed by , - * all of which will show up if we don't strip it here (example: http://cl.ly/image/0J0N3z3h1i04 ) - * first seen at http://houseofgeekery.com/2013/11/03/13-terrible-x-men-we-wont-see-in-the-movies/ + * may have a script block which contains {@code } followed by a CDATA section followed by {@code ,} + * all of which will show up if we don't strip it here. + * @see Wordpress Sociable Plugin + * @return String without {@code }, {@code } blocks followed by a CDATA section followed by {@code ,} + * @param text String containing script tags */ public static String stripScript(final String text) { if (text == null) { @@ -114,7 +126,10 @@ public static String stripScript(final String text) { } /** - * an alternative to Html.fromHtml() supporting
    ,
      ,
      tags and replacing EmoticonsUtils with Emojis + * An alternative to Html.fromHtml() supporting {@code
        }, {@code
          }, {@code
          } + * tags and replacing EmoticonsUtils with Emojis + * @param source + * @param wpImageGetter */ public static SpannableStringBuilder fromHtml(String source, WPImageGetter wpImageGetter) { SpannableStringBuilder html;