From a1d164e6371eaf81a8aaf0be1e1a9b16a1af43fc Mon Sep 17 00:00:00 2001
From: Gertjan van den Burg <burg@ese.eur.nl>
Date: Tue, 6 Dec 2016 16:26:01 +0100
Subject: document undocumented elements

---
 tests/include/dbg.h | 40 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 5 deletions(-)

(limited to 'tests/include/dbg.h')

diff --git a/tests/include/dbg.h b/tests/include/dbg.h
index 71137ba..3a68d0a 100644
--- a/tests/include/dbg.h
+++ b/tests/include/dbg.h
@@ -4,7 +4,7 @@
  * @author Zed Shaw
  *
  * @details
- * These debug macros come from Zed Shaw's book Learn C The Hard Way, and are 
+ * These debug macros come from Zed Shaw's book Learn C The Hard Way, and are
  * used for the testing framework of GenSVM.
  *
  * @sa minunit.h
@@ -18,31 +18,61 @@
 #include <string.h>
 
 #ifdef NDEBUG
-#define debug(M, ...)
+  /**
+   * Define debug macro as doing nothing when we don't want debug output
+   */
+  #define debug(M, ...)
 #else
-#define debug(M, ...) fprintf(stderr, "DEBUG %s:%d: " M "\n", __FILE__, \
-		__LINE__, ##__VA_ARGS__)
+  /**
+   * Print debug info to stderr
+   */
+  #define debug(M, ...) fprintf(stderr, "DEBUG %s:%d: " M "\n", __FILE__, \
+  		__LINE__, ##__VA_ARGS__)
 #endif
 
+/**
+ * Return a clean string of the current errno
+ */
 #define clean_errno() (errno == 0 ? "None" : strerror(errno))
 
+/**
+ * Log an error to stderr
+ */
 #define log_err(M, ...) fprintf(stderr, "[ERROR] (%s:%d: errno: %s) " M "\n", \
 		__FILE__, __LINE__, clean_errno(), ##__VA_ARGS__)
 
+/**
+ * Log a warning to stderr
+ */
 #define log_warn(M, ...) fprintf(stderr, "[WARN] (%s:%d: errno: %s) " M "\n", \
 		__FILE__, __LINE__, clean_errno(), ##__VA_ARGS__)
 
+/**
+ * Log info to stderr
+ */
 #define log_info(M, ...) fprintf(stderr, "[INFO] (%s:%d) " M "\n", \
 		__FILE__, __LINE__, ##__VA_ARGS__)
 
+/**
+ * Check a condition an log an error with the given message if it fails
+ */
 #define check(A, M, ...) if(!(A)) { log_err(M, ##__VA_ARGS__); errno=0; \
 	goto error; }
 
+/**
+ * Log an error with the given message and reset errno
+ */
 #define sentinel(M, ...) { log_err(M, ##__VA_ARGS__); errno=0; goto error; }
 
+/**
+ * Check a memory allocation
+ */
 #define check_mem(A) check((A), "Out of memory.");
 
+/**
+ * Check a condition and log to debug if it fails, and reset errno
+ */
 #define check_debug(A, M, ...) if (!(A)) { debug(M, ##__VA_ARGS__); errno=0; \
-	goto error; }
+  	goto error; }
 
 #endif
-- 
cgit v1.2.3