Doxygen format <android/log.h>.
Bug: N/A
Test: ran doxygen manually.
Change-Id: I164de255dbbc6c0312e656ddd886dcac231c893a
diff --git a/liblog/include/android/log.h b/liblog/include/android/log.h
index 15fba8b..ade2821 100644
--- a/liblog/include/android/log.h
+++ b/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 @@
#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 @@
#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,
...)