diff options
author | Elliott Hughes <enh@google.com> | 2018-01-26 10:57:10 -0800 |
---|---|---|
committer | Elliott Hughes <enh@google.com> | 2018-01-26 10:57:57 -0800 |
commit | 65725ac4646f8c243215f87df0abb8c96caea0ae (patch) | |
tree | 084bc07bed6599b877df2969e78e0e679079d141 /liblog | |
parent | a0e50d0b56f6f831f81344f3a36e5733092c16d0 (diff) | |
download | system_core-65725ac4646f8c243215f87df0abb8c96caea0ae.tar.gz system_core-65725ac4646f8c243215f87df0abb8c96caea0ae.tar.bz2 system_core-65725ac4646f8c243215f87df0abb8c96caea0ae.zip |
Doxygen format <android/log.h>.
Bug: N/A
Test: ran doxygen manually.
Change-Id: I164de255dbbc6c0312e656ddd886dcac231c893a
Diffstat (limited to 'liblog')
-rw-r--r-- | liblog/include/android/log.h | 65 |
1 files changed, 44 insertions, 21 deletions
diff --git a/liblog/include/android/log.h b/liblog/include/android/log.h index 15fba8b72..ade282187 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 @@ 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, ...) |