diff --git a/doc/manual/style.txt b/doc/manual/style.txt index a1e6b8f016..dc27e8767a 100644 --- a/doc/manual/style.txt +++ b/doc/manual/style.txt @@ -225,6 +225,21 @@ if (!buf) { } @endcode +@section stylelogging Logging + +Logging is intended to provide human-readable information to users. +Do not confuse logging with the output of commands. +The latter is intended for the result of a command and should be able to be processed by Tcl scripts. + + - Use one of the following functions to generate log messages, never use `printf()` or similar functions. + - Use `LOG_ERROR()` to provide information in case an operation failed in an unrecoverable way. For example, if necessary memory cannot be allocated. + - Use `LOG_WARNING()` to inform the user of about an unexpected behavior that can be handled and the intended operation is still be performed. For example, in case a command is deprecated but is nevertheless executed. + - Use `LOG_INFO()` to provide insightful or necessary information to the user. For example, features or capabilities of a discovered target. + - Use `LOG_DEBUG()` to provide information for troubleshooting. For example, detailed information which makes it easier to debug a specific operation. Try to avoid flooding the log with frequently generated messages. For example, do not use LOG_DEBUG() in operations used for polling the target. Use LOG_DEBUG_IO() for such frequent messages. + - Use `LOG_DEBUG_IO()` to provide I/O related information for troubleshooting. For example, details about the communication between OpenOCD and a debug adapter. + - If the log message is related to a target, use the corresponding `LOG_TARGET_xxx()` functions. + - Do not use a period or exclamation mark at the end of a message. + */ /** @page styledoxygen Doxygen Style Guide