interesting
/
riscv-openocd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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:
Marc Schink 2024-10-23 15:42:16 +02:00 committed by Antonio Borneo
parent cc02bd752c
commit 1710954977
1 changed files with 15 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
doc/manual/style.txt
View File

@ -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