add better comments to lily-test.h

1 files changed, 29 insertions, 1 deletions

diff --git a/lily-test.h b/lily-test.h
index b9a57f7..6ada538 100644
--- a/lily-test.h
+++ b/lily-test.h
@@ -16,20 +16,22 @@
 #define LILY_LOCATION ((__FILE__ ":" STR(__LINE__)) + SOURCE_PATH_SIZE)
 #endif
 
+/** a few nasty globals that make everything clean for the end user */
 struct lily_globals_t {
    jmp_buf env;
    size_t error_msg_len;
    char *error_msg;
    const char *error_location;
 };
-
 extern struct lily_globals_t _lily_globals;
 
 typedef void (*lily_test_t)(void);
 
+/** run a single test */
 #define lily_run_test(test) _lily_run_test(#test, test)
 void _lily_run_test(const char *name, lily_test_t test);
 
+/** run a suite */
 #define lily_run_suite(suite) _lily_run_suite(#suite, suite);
 void _lily_run_suite(const char *name, lily_test_t suite);
 
@@ -41,6 +43,7 @@ void _lily_run_suite(const char *name, lily_test_t suite);
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  */
 
+/** basic assertion function, mostly used by the other assertions */
 void lily_assert_msg(bool statement, const char *location,
 		     const char *format_string, ...);
 
@@ -122,6 +125,7 @@ void _lily_assert_memory_not_equal(const char *name_a, const char *name_b,
  */
 
 
+/** queue structure capable of containing arbitrary data */
 typedef struct lily_queue_t {
    size_t buf_size;
    uint8_t *buf;
@@ -129,9 +133,19 @@ typedef struct lily_queue_t {
 } lily_queue_t;
 
 
+/** create a queue */
 lily_queue_t* lily_queue_create();
+
+/** destroy a queue */
 void lily_queue_destroy(lily_queue_t *q);
 
+
+/** enqueue a value
+ *
+ * q - the queue to append to
+ * type - the type of the value to append
+ * value - the value to append
+ */
 #define lily_enqueue(q, type, value)					\
    do {									\
       type _var = value;						\
@@ -140,6 +154,12 @@ void lily_queue_destroy(lily_queue_t *q);
 void _lily_enqueue(lily_queue_t *q, size_t size, uint8_t *data);
 
 
+/** pop a value from the queue
+ *
+ * q - the queue to pop from
+ * type - the type of the value to pop
+ * ptr - the location to store the popped value
+ */
 #define lily_dequeue(q, type, ptr)		\
    _lily_dequeue(q, sizeof(type), (uint8_t*) ptr)
 void _lily_dequeue(lily_queue_t *q, size_t size, uint8_t *ptr);
@@ -152,19 +172,25 @@ struct lily_mock_arg_t {
 
 #define LILY_NARGS(args) (sizeof(args)/sizeof(struct lily_mock_arg_t))
 
+/** structure to store data for mock functions */
 typedef struct lily_mock_t {
    unsigned int n_calls;
    lily_queue_t *arguments;
    lily_queue_t *values;
 } lily_mock_t;
 
+/** setup mock function storage */
 lily_mock_t * lily_mock_create();
+/** tear down mock function storage */
 void lily_mock_destroy(lily_mock_t *m);
 
+
+/** store a call to a mock function */
 #define lily_mock_call(m, args)			\
    _lily_mock_call(m, args, LILY_NARGS(args))
 void _lily_mock_call(lily_mock_t *m, struct lily_mock_arg_t *args, size_t n_args);
 
+/** retrieve a call to a mock function */
 #define lily_get_call(m, args, call_num)		\
    _lily_get_call(m, args, LILY_NARGS(args), call_num)
 void _lily_get_call(lily_mock_t *m,
@@ -172,8 +198,10 @@ void _lily_get_call(lily_mock_t *m,
 		    size_t n_args,
 		    unsigned int call_num);
 
+/** store a value in a mock structure */
 #define lily_store_value(m, type, value)	\
    lily_enqueue(m->values, type, value)
+/** retrieve a value from a mock structure */
 #define lily_get_value(m, type, ptr)		\
    lily_dequeue(m->values, type, ptr)