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>

diff --git a/doc/manual/style.txt b/doc/manual/style.txt
index a1e6b8f0164e177c23f114fa6a0d602ca16fda0b..dc27e8767acbcf143da0991177d2a4d9f65c8339 100644 (file)
--- 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