doc/manual: Add section about logging
The log messages are very inconsistent across the code base. Add a guideline for log messages to help improve consistency. The guideline is based on the most commonly used style in the current code base. Change-Id: I076d68abe588dd04b59580379e97b82d537def23 Signed-off-by: Marc Schink <dev@zapb.de> Reviewed-on: https://review.openocd.org/c/openocd/+/8576 Reviewed-by: Antonio Borneo <borneo.antonio@gmail.com> Tested-by: jenkins Reviewed-by: Tomas Vanek <vanekt@fbl.cz>
This commit is contained in:
parent
cc02bd752c
commit
1710954977
|
@ -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
|
||||
|
||||
|
|
Loading…
Reference in New Issue