From 50aee97fc209bdde21f745f6fe78364f36387821 Mon Sep 17 00:00:00 2001
From: nvt-se <nvt-se>
Date: Wed, 19 Jan 2011 05:09:57 +0000
Subject: [PATCH] More comments + minor adjustments to the header file

---
 apps/unit-test/example-test.c |  6 ++++++
 apps/unit-test/unit-test.h    | 18 +++++++++++++-----
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/apps/unit-test/example-test.c b/apps/unit-test/example-test.c
index ea19dedbb..b40dc525f 100644
--- a/apps/unit-test/example-test.c
+++ b/apps/unit-test/example-test.c
@@ -37,9 +37,13 @@
 #include "contiki.h"
 #include "unit-test.h"
 
+/* Register two unit tests that will be executed by using 
+   the UNIT_TEST_RUN macro. */
 UNIT_TEST_REGISTER(arithmetic, "Arith ops");
 UNIT_TEST_REGISTER(string, "String ops");
 
+/* arithmetic: Demonstrates a test that succeeds. The exit point will be 
+   the line where UNIT_TEST_END is called. */
 UNIT_TEST(arithmetic)
 {
   int a, b;
@@ -54,6 +58,8 @@ UNIT_TEST(arithmetic)
   UNIT_TEST_END();
 }
 
+/* string: Demonstrates a test that fails. The exit point will be 
+   the line where the call to UNIT_TEST_ASSERT fails. */
 UNIT_TEST(string)
 {
   char str1[] = "A";
diff --git a/apps/unit-test/unit-test.h b/apps/unit-test/unit-test.h
index 244b8b451..d11747cb0 100644
--- a/apps/unit-test/unit-test.h
+++ b/apps/unit-test/unit-test.h
@@ -44,10 +44,14 @@ typedef enum unit_test_result {
   unit_test_success = 1
 } unit_test_result_t;
 
+/**
+ * The unit_test structure describes the results of a unit test. Each 
+ * registered unit test statically allocates an object of this type.
+ */
 typedef struct unit_test {
   const char * const descr;
+  const char * const test_file;
   unit_test_result_t result;
-  const char *test_file;
   unsigned exit_line;
   rtimer_clock_t start;
   rtimer_clock_t end;
@@ -63,7 +67,7 @@ typedef struct unit_test {
  * \param name The name of the unit test.
  * \param descr A string that briefly describes the unit test.
  */
-#define UNIT_TEST_REGISTER(name, descr) static unit_test_t unit_test_##name = {descr, unit_test_success, __FILE__, 0, 0, 0}
+#define UNIT_TEST_REGISTER(name, descr) static unit_test_t unit_test_##name = {descr, __FILE__, unit_test_success, 0, 0, 0}
 
 /**
  * Define a unit test.
@@ -117,14 +121,17 @@ typedef struct unit_test {
  *
  * \param name The name of the unit test.
  */
-#define UNIT_TEST_PRINT_REPORT(name) UNIT_TEST_PRINT_FUNCTION(&unit_test_##name);
+#define UNIT_TEST_PRINT_REPORT(name) UNIT_TEST_PRINT_FUNCTION(&unit_test_##name)
 
 /**
- * Execute a unit test.
+ * Execute a unit test and print a report on the results.
  *
  * \param name The name of the unit test.
  */
-#define UNIT_TEST_RUN(name)  unit_test_function_##name(&unit_test_##name); UNIT_TEST_PRINT_REPORT(name);
+#define UNIT_TEST_RUN(name)  do {                                             \
+                               unit_test_function_##name(&unit_test_##name);  \
+                               UNIT_TEST_PRINT_REPORT(name);                  \
+                             } while(0)
 
 /**
  * Report that a unit test succeeded.
@@ -167,6 +174,7 @@ typedef struct unit_test {
                                  }                                            \
                                } while(0)
 
+/* The default print function. */
 void unit_test_print_report(const unit_test_t *utp);
 
 #endif /* !UNIT_TEST_H */