From 1710954977a0262e6987426f117aab0f73b27024 Mon Sep 17 00:00:00 2001 From: Marc Schink Date: Wed, 23 Oct 2024 15:42:16 +0200 Subject: [PATCH] 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 Reviewed-on: https://review.openocd.org/c/openocd/+/8576 Reviewed-by: Antonio Borneo Tested-by: jenkins Reviewed-by: Tomas Vanek --- doc/manual/style.txt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) 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