Mercurial > hg > ucx / changeset

--- a/src/cx/test.h	Sat Jan 04 18:34:13 2025 +0100
+++ b/src/cx/test.h	Sat Jan 04 18:40:29 2025 +0100
@@ -35,13 +35,13 @@
  *
  * **** IN HEADER FILE: ****
  *
- * <pre>
+ * <code>
  * CX_TEST(function_name);
  * CX_TEST_SUBROUTINE(subroutine_name, paramlist); // optional
- * </pre>
+ * </code>
  *
  * **** IN SOURCE FILE: ****
- * <pre>
+ * <code>
  * CX_TEST_SUBROUTINE(subroutine_name, paramlist) {
  *   // tests with CX_TEST_ASSERT()
  * }
@@ -54,7 +54,7 @@
  *   }
  *   // cleanup of memory here
  * }
- * </pre>
+ * </code>
  * 
  * @attention Do not call own functions within a test, that use
  * CX_TEST_ASSERT() macros and are not defined by using CX_TEST_SUBROUTINE().
@@ -87,7 +87,6 @@
 #define __FUNCTION__ __func__
 #endif
 
-//
 #if !defined(__clang__) && __GNUC__ > 3
 #pragma GCC diagnostic ignored "-Wclobbered"
 #endif
@@ -96,7 +95,6 @@
 typedef struct CxTestSuite CxTestSuite;
 
 /** Pointer to a test function. */
-cx_attr_nonnull
 typedef void(*CxTest)(CxTestSuite *, void *, cx_write_func);
 
 /** Type for the internal list of test cases. */
@@ -175,7 +173,8 @@
  * 
  * @param suite the suite, the test function shall be added to
  * @param test the test function to register
- * @return zero on success or non-zero on failure
+ * @retval zero success
+ * @retval non-zero failure
  */
 cx_attr_nonnull
 static inline int cx_test_register(CxTestSuite* suite, CxTest test) {
@@ -202,7 +201,7 @@
  * Runs a test suite and writes the test log to the specified stream.
  * @param suite the test suite to run
  * @param out_target the target buffer or file to write the output to
- * @param out_writer the write function writing to \p out_target
+ * @param out_writer the write function writing to @p out_target
  */
 cx_attr_nonnull
 static inline void cx_test_run(CxTestSuite *suite,
@@ -231,14 +230,14 @@
 
 /**
  * Runs a test suite and writes the test log to the specified FILE stream.
- * @param suite the test suite to run
- * @param file the target file to write the output to
+ * @param suite (@c CxTestSuite*) the test suite to run
+ * @param file (@c FILE*) the target file to write the output to
  */
 #define cx_test_run_f(suite, file) cx_test_run(suite, (void*)file, (cx_write_func)fwrite)
 
 /**
  * Runs a test suite and writes the test log to stdout.
- * @param suite the test suite to run
+ * @param suite (@c CxTestSuite*) the test suite to run
  */
 #define cx_test_run_stdout(suite) cx_test_run_f(suite, stdout)
 
@@ -253,6 +252,17 @@
 
 /**
  * Defines the scope of a test.
+ *
+ * @code
+ * CX_TEST(my_test_name) {
+ *     // setup code
+ *     CX_TEST_DO {
+ *         // your tests go here
+ *     }
+ *     // tear down code
+ * }
+ * @endcode
+ *
  * @attention Any CX_TEST_ASSERT() calls must be performed in scope of
  * #CX_TEST_DO.
  */
@@ -270,8 +280,8 @@
  * If the assertion is correct, the test carries on. If the assertion is not
  * correct, the specified message (terminated by a dot and a line break) is
  * written to the test suites output stream.
- * @param condition the condition to check
- * @param message the message that shall be printed out on failure
+ * @param condition (@c bool) the condition to check
+ * @param message (@c char*) the message that shall be printed out on failure
  */
 #define CX_TEST_ASSERTM(condition,message) if (!(condition)) { \
         const char *_assert_msg_ = message; \
@@ -286,7 +296,7 @@
  * If the assertion is correct, the test carries on. If the assertion is not
  * correct, the specified message (terminated by a dot and a line break) is
  * written to the test suites output stream.
- * @param condition the condition to check
+ * @param condition (@c bool) the condition to check
  */
 #define CX_TEST_ASSERT(condition) CX_TEST_ASSERTM(condition, #condition " failed")