[OpenOCD-commit] Main OpenOCD repository branch, master, updated. v0.12.0-805-g171095497

[openocd-gerrit <ope...@us...>]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "Main OpenOCD repository".

The branch, master has been updated
       via  1710954977a0262e6987426f117aab0f73b27024 (commit)
      from  cc02bd752c13e1810b0b56593e6c5edcd179f484 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 1710954977a0262e6987426f117aab0f73b27024
Author: Marc Schink <de...@za...>
Date:   Wed Oct 23 15:42:16 2024 +0200

    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 <de...@za...>
    Reviewed-on: https://review.openocd.org/c/openocd/+/8576
    Reviewed-by: Antonio Borneo <bor...@gm...>
    Tested-by: jenkins
    Reviewed-by: Tomas Vanek <va...@fb...>

diff --git a/doc/manual/style.txt b/doc/manual/style.txt
index a1e6b8f01..dc27e8767 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
 

-----------------------------------------------------------------------

Summary of changes:
 doc/manual/style.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)


hooks/post-receive
-- 
Main OpenOCD repository