document undocumented elements

2 files changed, 55 insertions, 5 deletions

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
diff --git a/tests/include/minunit.h b/tests/include/minunit.h
index 9e2328f..204b321 100644
--- a/tests/include/minunit.h
+++ b/tests/include/minunit.h
@@ -18,13 +18,27 @@
 #include "dbg.h"
 #include <stdlib.h>
 
+/**
+ * Start the unit testing suite by creating an empty message
+ */
 #define mu_suite_start() char *message = NULL
 
+/**
+ * Check a condition and log the message as an error if it fails
+ */
 #define mu_assert(test, message) if (!(test)) { log_err(message); return message; }
 
+/**
+ * Run a test function, return the message if there is one, increment 
+ * tests_run
+ */
 #define mu_run_test(test) debug("\n-----%s", " " #test); \
 	message = test(); tests_run++; if (message) return message;
 
+/**
+ * Definition of main function for the test framework. Defines the output 
+ * presented to stdout/stderr and runs all_tests function provided by "name"
+ */
 #define RUN_TESTS(name) int main(int argc, char *argv[]) {\
 	argc = 1; \
 	debug("\n-----\nRUNNING: %s", argv[0]);\
@@ -40,9 +54,15 @@
 	exit(result != 0);\
 }
 
+/**
+ * Log a warning to stdout when a test is missing and reduce tests_run by 1.
+ */
 #define mu_test_missing() printf("\033[33;1mWARNING: Test missing\033[0m\n");\
 	tests_run--;
 
+/**
+ * Global counter for the number of tests that have been run.
+ */
 int tests_run;
 
 #endif