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
 
-

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, ...);