Merge "Doxygen format <android/log.h>."

am: 969539c5c8

Change-Id: I4a8f17d666da7084790b99d79fcd289896416f45

liblog/include/android/log.h

@@ -34,9 +34,11 @@
  *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
  */
 
-/*
- * Support routines to send messages to the Android in-kernel log buffer,
- * which can later be accessed through the 'logcat' utility.
+/**
+ * \file
+ *
+ * Support routines to send messages to the Android log buffer,
+ * which can later be accessed through the `logcat` utility.
  *
  * Each log message must have
  *   - a priority
@@ -47,24 +49,22 @@
  * and should be reasonably small.
  *
  * Log message text may be truncated to less than an implementation-specific
- * limit (e.g. 1023 characters max).
+ * limit (1023 bytes).
  *
  * Note that a newline character ("\n") will be appended automatically to your
  * log message, if not already there. It is not possible to send several
  * messages and have them appear on a single line in logcat.
  *
- * PLEASE USE LOGS WITH MODERATION:
+ * Please use logging in moderation:
  *
  *  - Sending log messages eats CPU and slow down your application and the
  *    system.
  *
- *  - The circular log buffer is pretty small (<64KB), sending many messages
- *    might push off other important log messages from the rest of the system.
+ *  - The circular log buffer is pretty small, so sending many messages
+ *    will hide other important log messages.
  *
  *  - In release builds, only send log messages to account for exceptional
  *    conditions.
- *
- * NOTE: These functions MUST be implemented by /system/lib/liblog.so
  */
 
 #include <stdarg.h>
@@ -73,28 +73,40 @@
 extern "C" {
 #endif
 
-/*
- * Android log priority values, in ascending priority order.
+/**
+ * Android log priority values, in increasing order of priority.
  */
 typedef enum android_LogPriority {
+  /** For internal use only.  */
   ANDROID_LOG_UNKNOWN = 0,
+  /** The default priority, for internal use only.  */
   ANDROID_LOG_DEFAULT, /* only for SetMinPriority() */
+  /** Verbose logging. Should typically be disabled for a release apk. */
   ANDROID_LOG_VERBOSE,
+  /** Debug logging. Should typically be disabled for a release apk. */
   ANDROID_LOG_DEBUG,
+  /** Informational logging. Should typically be disabled for a release apk. */
   ANDROID_LOG_INFO,
+  /** Warning logging. For use with recoverable failures. */
   ANDROID_LOG_WARN,
+  /** Error logging. For use with unrecoverable failures. */
   ANDROID_LOG_ERROR,
+  /** Fatal logging. For use when aborting. */
   ANDROID_LOG_FATAL,
+  /** For internal use only.  */
   ANDROID_LOG_SILENT, /* only for SetMinPriority(); must be last */
 } android_LogPriority;
 
-/*
- * Send a simple string to the log.
+/**
+ * Writes the constant string `text` to the log, with priority `prio` and tag
+ * `tag`.
  */
 int __android_log_write(int prio, const char* tag, const char* text);
 
-/*
- * Send a formatted string to the log, used like printf(fmt,...)
+/**
+ * Writes a formatted string to the log, with priority `prio` and tag `tag`.
+ * The details of formatting are the same as for
+ * [printf(3)](http://man7.org/linux/man-pages/man3/printf.3.html).
  */
 int __android_log_print(int prio, const char* tag, const char* fmt, ...)
 #if defined(__GNUC__)
@@ -110,9 +122,9 @@ int __android_log_print(int prio, const char* tag, const char* fmt, ...)
 #endif
     ;
 
-/*
- * A variant of __android_log_print() that takes a va_list to list
- * additional parameters.
+/**
+ * Equivalent to `__android_log_print`, but taking a `va_list`.
+ * (If `__android_log_print` is like `printf`, this is like `vprintf`.)
  */
 int __android_log_vprint(int prio, const char* tag, const char* fmt, va_list ap)
 #if defined(__GNUC__)
@@ -128,9 +140,20 @@ int __android_log_vprint(int prio, const char* tag, const char* fmt, va_list ap)
 #endif
     ;
 
-/*
- * Log an assertion failure and abort the process to have a chance
- * to inspect it if a debugger is attached. This uses the FATAL priority.
+/**
+ * Writes an assertion failure to the log (as `ANDROID_LOG_FATAL`) and to
+ * stderr, before calling
+ * [abort(3)](http://man7.org/linux/man-pages/man3/abort.3.html).
+ *
+ * If `fmt` is non-null, `cond` is unused. If `fmt` is null, the string
+ * `Assertion failed: %s` is used with `cond` as the string argument.
+ * If both `fmt` and `cond` are null, a default string is provided.
+ *
+ * Most callers should use
+ * [assert(3)](http://man7.org/linux/man-pages/man3/assert.3.html) from
+ * `<assert.h>` instead, or the `__assert` and `__assert2` functions provided by
+ * bionic if more control is needed. They support automatically including the
+ * source filename and line number more conveniently than this function.
  */
 void __android_log_assert(const char* cond, const char* tag, const char* fmt,
                           ...)