Merge "Document return values from android.util.Log logging functions"

1 files changed, 37 insertions, 9 deletions

diff --git a/core/java/android/util/Log.java b/core/java/android/util/Log.java
index b5fe4f58dfb2..f1e91d0234e4 100644
--- a/core/java/android/util/Log.java
+++ b/core/java/android/util/Log.java
@@ -66,6 +66,10 @@ import java.net.UnknownHostException;
  * <p>When calling the log methods that take a Throwable parameter,
  * if any of the throwables in the cause chain is an <code>UnknownHostException</code>,
  * then the stack trace is not logged.
+ *
+ * <p>Note: The return value from the logging functions in this class may vary between Android
+ * releases due to changes in the logging implementation. For the methods that return an integer,
+ * a positive value may be considered as a successful invocation.
  */
 public final class Log {
     /** @hide */
@@ -134,6 +138,7 @@ public final class Log {
      * @param tag Used to identify the source of a log message.  It usually identifies
      *        the class or activity where the log call occurs.
      * @param msg The message you would like logged.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int v(@Nullable String tag, @NonNull String msg) {
         return println_native(LOG_ID_MAIN, VERBOSE, tag, msg);
@@ -144,7 +149,8 @@ public final class Log {
      * @param tag Used to identify the source of a log message.  It usually identifies
      *        the class or activity where the log call occurs.
      * @param msg The message you would like logged.
-     * @param tr An exception to log
+     * @param tr An exception to log.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int v(@Nullable String tag, @Nullable String msg, @Nullable Throwable tr) {
         return printlns(LOG_ID_MAIN, VERBOSE, tag, msg, tr);
@@ -155,6 +161,7 @@ public final class Log {
      * @param tag Used to identify the source of a log message.  It usually identifies
      *        the class or activity where the log call occurs.
      * @param msg The message you would like logged.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int d(@Nullable String tag, @NonNull String msg) {
         return println_native(LOG_ID_MAIN, DEBUG, tag, msg);
@@ -165,7 +172,8 @@ public final class Log {
      * @param tag Used to identify the source of a log message.  It usually identifies
      *        the class or activity where the log call occurs.
      * @param msg The message you would like logged.
-     * @param tr An exception to log
+     * @param tr An exception to log.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int d(@Nullable String tag, @Nullable String msg, @Nullable Throwable tr) {
         return printlns(LOG_ID_MAIN, DEBUG, tag, msg, tr);
@@ -176,6 +184,7 @@ public final class Log {
      * @param tag Used to identify the source of a log message.  It usually identifies
      *        the class or activity where the log call occurs.
      * @param msg The message you would like logged.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int i(@Nullable String tag, @NonNull String msg) {
         return println_native(LOG_ID_MAIN, INFO, tag, msg);
@@ -186,7 +195,7 @@ public final class Log {
      * @param tag Used to identify the source of a log message.  It usually identifies
      *        the class or activity where the log call occurs.
      * @param msg The message you would like logged.
-     * @param tr An exception to log
+     * @param tr An exception to log.
      */
     public static int i(@Nullable String tag, @Nullable String msg, @Nullable Throwable tr) {
         return printlns(LOG_ID_MAIN, INFO, tag, msg, tr);
@@ -197,6 +206,7 @@ public final class Log {
      * @param tag Used to identify the source of a log message.  It usually identifies
      *        the class or activity where the log call occurs.
      * @param msg The message you would like logged.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int w(@Nullable String tag, @NonNull String msg) {
         return println_native(LOG_ID_MAIN, WARN, tag, msg);
@@ -207,7 +217,8 @@ public final class Log {
      * @param tag Used to identify the source of a log message.  It usually identifies
      *        the class or activity where the log call occurs.
      * @param msg The message you would like logged.
-     * @param tr An exception to log
+     * @param tr An exception to log.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int w(@Nullable String tag, @Nullable String msg, @Nullable Throwable tr) {
         return printlns(LOG_ID_MAIN, WARN, tag, msg, tr);
@@ -239,7 +250,8 @@ public final class Log {
      * Send a {@link #WARN} 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 tr An exception to log
+     * @param tr An exception to log.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int w(@Nullable String tag, @Nullable Throwable tr) {
         return printlns(LOG_ID_MAIN, WARN, tag, "", tr);
@@ -250,6 +262,7 @@ public final class Log {
      * @param tag Used to identify the source of a log message.  It usually identifies
      *        the class or activity where the log call occurs.
      * @param msg The message you would like logged.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int e(@Nullable String tag, @NonNull String msg) {
         return println_native(LOG_ID_MAIN, ERROR, tag, msg);
@@ -260,7 +273,8 @@ public final class Log {
      * @param tag Used to identify the source of a log message.  It usually identifies
      *        the class or activity where the log call occurs.
      * @param msg The message you would like logged.
-     * @param tr An exception to log
+     * @param tr An exception to log.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int e(@Nullable String tag, @Nullable String msg, @Nullable Throwable tr) {
         return printlns(LOG_ID_MAIN, ERROR, tag, msg, tr);
@@ -274,6 +288,7 @@ public final class Log {
      * immediately with an error dialog.
      * @param tag Used to identify the source of a log message.
      * @param msg The message you would like logged.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int wtf(@Nullable String tag, @Nullable String msg) {
         return wtf(LOG_ID_MAIN, tag, msg, null, false, false);
@@ -293,6 +308,7 @@ public final class Log {
      * Similar to {@link #wtf(String, String)}, with an exception to log.
      * @param tag Used to identify the source of a log message.
      * @param tr An exception to log.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int wtf(@Nullable String tag, @NonNull Throwable tr) {
         return wtf(LOG_ID_MAIN, tag, tr.getMessage(), tr, false, false);
@@ -304,6 +320,7 @@ public final class Log {
      * @param tag Used to identify the source of a log message.
      * @param msg The message you would like logged.
      * @param tr An exception to log.  May be null.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int wtf(@Nullable String tag, @Nullable String msg, @Nullable Throwable tr) {
         return wtf(LOG_ID_MAIN, tag, msg, tr, false, false);
@@ -348,7 +365,7 @@ public final class Log {
 
      * <p>If any of the throwables in the cause chain is an <code>UnknownHostException</code>,
      * this returns an empty string.
-     * @param tr An exception to log
+     * @param tr An exception to log.
      */
     @NonNull
     public static String getStackTraceString(@Nullable Throwable tr) {
@@ -379,7 +396,7 @@ public final class Log {
      * @param tag Used to identify the source of a log message.  It usually identifies
      *        the class or activity where the log call occurs.
      * @param msg The message you would like logged.
-     * @return The number of bytes written.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      */
     public static int println(@Level int priority, @Nullable String tag, @NonNull String msg) {
         return println_native(LOG_ID_MAIN, priority, tag, msg);
@@ -391,7 +408,16 @@ public final class Log {
     /** @hide */ public static final int LOG_ID_SYSTEM = 3;
     /** @hide */ public static final int LOG_ID_CRASH = 4;
 
-    /** @hide */
+    /**
+     * Low-level logging call.
+     * @param bufID The buffer ID to receive the message.
+     * @param priority The priority of the 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 msg The message you would like logged.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
+     * @hide
+     */
     @UnsupportedAppUsage
     public static native int println_native(int bufID, int priority, String tag, String msg);
 
@@ -407,6 +433,7 @@ public final class Log {
      * @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.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      * @hide
      */
     @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
@@ -425,6 +452,7 @@ public final class Log {
      * Helper function for long messages. Uses the LineBreakBufferedWriter to break
      * up long messages and stacktraces along newlines, but tries to write in large
      * chunks. This is to avoid truncation.
+     * @return A positive value if the message was loggable (see {@link #isLoggable}).
      * @hide
      */
     public static int printlns(int bufID, int priority, @Nullable String tag, @NonNull String msg,