include: Document run_tests().

diff --git a/include/cmocka.h b/include/cmocka.h
index 28cf84949810a58c2281b251cb150c2e2105fb76..f99706bd0ab85b95b49cc708004b5acd102a4c57 100755 (executable)
--- a/include/cmocka.h
+++ b/include/cmocka.h
@@ -402,8 +402,28 @@ void fail(void);
 #define fail() _fail(__FILE__, __LINE__)
 #endif
 
-/* Generic method to kick off testing */
+#ifdef DOXYGEN
+/**
+ * @brief Generic method to run a single test.
+ *
+ * @param[in]  #function The function to test.
+ *
+ * @return 0 on success, 1 if an error occured.
+ *
+ * @code
+ * // A test case that does nothing and succeeds.
+ * void null_test_success(void **state) {
+ * }
+ *
+ * int main(void) {
+ *      return run_test(null_test_success);
+ * }
+ * @endcode
+ */
+int run_test(#function);
+#else
 #define run_test(f) _run_test(#f, f, NULL, UNIT_TEST_FUNCTION_TYPE_TEST, NULL)
+#endif
 
 /* Initializes a UnitTest structure. */
 #define unit_test(f) { #f, f, UNIT_TEST_FUNCTION_TYPE_TEST }