From 97d2587c312bb32048d737a50771872b8832e462 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jere=20Lepp=C3=A4nen?= <jere.leppanen@nokia.com>
Date: Tue, 3 Dec 2024 17:03:05 +0200
Subject: [PATCH] helper: debug: improve macro documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a few details to the documentation of debug macros.

Signed-off-by: Jere Leppänen <jere.leppanen@nokia.com>
Reviewed-by: Matias Elo <matias.elo@nokia.com>
Reviewed-by: Tuomas Taipale <tuomas.taipale@nokia.com>
---
 helper/include/odp/helper/debug.h | 31 ++++++++++++++++++++-----------
 1 file changed, 20 insertions(+), 11 deletions(-)

diff --git a/helper/include/odp/helper/debug.h b/helper/include/odp/helper/debug.h
index 53aa03bbeb..35253001ba 100644
--- a/helper/include/odp/helper/debug.h
+++ b/helper/include/odp/helper/debug.h
@@ -1,6 +1,6 @@
 /* SPDX-License-Identifier: BSD-3-Clause
  * Copyright (c) 2015-2018 Linaro Limited
- * Copyright (c) 2019 Nokia
+ * Copyright (c) 2019-2024 Nokia
  */
 
 /**
@@ -35,7 +35,7 @@ extern "C" {
  */
 
 /**
- * log level.
+ * Log level
  */
 typedef enum odph_log_level {
 	ODPH_LOG_DBG,
@@ -44,7 +44,15 @@ typedef enum odph_log_level {
 } odph_log_level_e;
 
 /**
- * default LOG macro.
+ * Output a log with file, line and function information.
+ *
+ * Outputs a log if level is not ODPH_LOG_DBG, or if ODPH_DEBUG_PRINT is enabled
+ * (--enable-helper-debug-print configure option). Calls odp_log_fn_get() to get
+ * the current log function. If no log function is set, prints to stderr.
+ *
+ * Additionally, if level is ODPH_LOG_ABORT, calls odp_abort_fn_get() to get the
+ * current abort function and calls it to abort the application. If no abort
+ * function is set, calls abort().
  */
 #define ODPH_LOG(level, fmt, ...) \
 do { \
@@ -70,10 +78,9 @@ do { \
 } while (0)
 
 /**
- * Assert macro for applications and helper code
- *
- * No code is generated when ODPH_DEBUG=0. Prints error message and aborts when
- * ODPH_DEBUG=1 and 'cond' is false.
+ * Runtime assertion macro. No code is generated when ODPH_DEBUG=0. Prints error
+ * message and aborts when ODPH_DEBUG=1 (--enable-helper-debug configure option)
+ * and 'cond' is false.
  */
 #define ODPH_ASSERT(cond) \
 	do { \
@@ -82,7 +89,8 @@ do { \
 	} while (0)
 
 /**
- * Debug printing macro, which prints output when DEBUG flag is set.
+ * Debug log macro. Outputs a log with level ODPH_LOG_DBG. See ODPH_LOG() for
+ * more information.
  */
 #define ODPH_DBG(...) \
 	do { \
@@ -92,7 +100,8 @@ do { \
 	} while (0)
 
 /**
- * Print output to stderr (file, line and function).
+ * Error log macro. Outputs a log with level ODPH_LOG_ERR. See ODPH_LOG() for
+ * more information.
  */
 #define ODPH_ERR(...) \
 	do { \
@@ -102,8 +111,8 @@ do { \
 	} while (0)
 
 /**
- * Print output to stderr (file, line and function),
- * then abort.
+ * Abort macro. Outputs a log with level ODPH_LOG_ABORT and aborts the
+ * application. See ODPH_LOG() for more information.
  */
 #define ODPH_ABORT(...) \
 	do { \