From 12800818ce40f12979c2c50da6f95fd3d3f1fff2 Mon Sep 17 00:00:00 2001
From: Steins7 <steinsset@gmail.com>
Date: Sat, 20 Apr 2024 11:44:56 +0200
Subject: [PATCH] Document debug module

---
 srv/debug.c |  4 +++-
 srv/debug.h | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/srv/debug.c b/srv/debug.c
index 23d3794..416880c 100644
--- a/srv/debug.c
+++ b/srv/debug.c
@@ -62,6 +62,9 @@ void _debug_print(const char* restrict header,
 
 //--local functions-------------------------------------------------------------
 
+/**
+ * Callback to use with format_vfctprintf() to print caracters to the debug port
+ */
 static uint32_t write_debug(uint8_t c, void* arg)
 {
 	(void)arg; //unused, required because of FormatCallback
@@ -77,4 +80,3 @@ static uint32_t write_debug(uint8_t c, void* arg)
 
 #endif //DEBUG_TRACE || DEBUG_WARN || DEBUG_ERROR
 
-
diff --git a/srv/debug.h b/srv/debug.h
index 7fcb31d..523b117 100644
--- a/srv/debug.h
+++ b/srv/debug.h
@@ -27,6 +27,12 @@
 #endif
 
 #if DEBUG_TRACE
+/**
+ * Prints a trace message on the debug port. This function should return
+ * immediately, provided that the message's length doesn't exceed 80 caracters
+ * and that it isn't called in very quick succession. Otherwise, it will block
+ * until the internal buffering system is ready to accept the message
+ */
 #define debug_trace(format, ...) _debug_print("T:", \
 		format __VA_OPT__(,) __VA_ARGS__)
 #else
@@ -34,6 +40,12 @@
 #endif
 
 #if DEBUG_WARN
+/**
+ * Prints a warning message on the debug port. This function should return
+ * immediately, provided that the message's length doesn't exceed 80 caracters
+ * and that it isn't called in very quick succession. Otherwise, it will block
+ * until the internal buffering system is ready to accept the message
+ */
 #define debug_warn(format, ...) _debug_print("W:", \
 		format __VA_OPT__(,) __VA_ARGS__)
 #else
@@ -41,6 +53,12 @@
 #endif
 
 #if DEBUG_ERROR
+/**
+ * Prints an error message on the debug port. This function should return
+ * immediately, provided that the message's length doesn't exceed 80 caracters
+ * and that it isn't called in very quick succession. Otherwise, it will block
+ * until the internal buffering system is ready to accept the message
+ */
 #define debug_error(format, ...) _debug_print("E:", \
 		format __VA_OPT__(,) __VA_ARGS__)
 #else
@@ -52,9 +70,24 @@
 
 #if DEBUG_TRACE || DEBUG_WARN || DEBUG_ERROR
 
+/**
+ * Initializes the debug system to use the given usart peripheral on the given
+ * tx port, printing a banner if traces are enabled.
+ * The usart doesn't need to be configured, neither does the tx port.
+ *
+ * This function shouldn't be called directly. Instead, use the debug_init macro
+ */
 void _debug_init(enum UsartPeriph usart, enum GpioPort tx_port,
 		enum GpioPin tx_pin);
 
+/**
+ * Prints a debug message on the debug port with the given header. This function
+ * should return immediately, provided that the message's length doesn't exceed
+ * 80 caracters and that it isn't called in very quick succession. Otherwise, it
+ * will block until the internal buffering system is ready to accept the message
+ *
+ * This function shouldn't be called directly. Instead, use the debug macros
+ */
 void _debug_print(const char* restrict header,
 		const char* restrict format, ...);