Mercurial > hg > toolkit / file diff

--- a/ucx/cx/test.h	Sun Jan 05 17:41:39 2025 +0100
+++ b/ucx/cx/test.h	Sun Jan 05 22:00:39 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().
@@ -67,7 +67,8 @@
 #ifndef UCX_TEST_H
 #define	UCX_TEST_H
 
-#include <stdlib.h>
+#include "common.h"
+
 #include <stdio.h>
 #include <string.h>
 #include <setjmp.h>
@@ -86,23 +87,10 @@
 #define __FUNCTION__ __func__
 #endif
 
-//
 #if !defined(__clang__) && __GNUC__ > 3
 #pragma GCC diagnostic ignored "-Wclobbered"
 #endif
 
-#ifndef UCX_COMMON_H
-/**
- * Function pointer compatible with fwrite-like functions.
- */
-typedef size_t (*cx_write_func)(
-        const void *,
-        size_t,
-        size_t,
-        void *
-);
-#endif // UCX_COMMON_H
-
 /** Type for the CxTestSuite. */
 typedef struct CxTestSuite CxTestSuite;
 
@@ -148,6 +136,10 @@
  * @param name optional name of the suite
  * @return a new test suite
  */
+cx_attr_nonnull
+cx_attr_nodiscard
+cx_attr_cstr_arg(1)
+cx_attr_malloc
 static inline CxTestSuite* cx_test_suite_new(const char *name) {
     CxTestSuite* suite = (CxTestSuite*) malloc(sizeof(CxTestSuite));
     if (suite != NULL) {
@@ -161,10 +153,12 @@
 }
 
 /**
- * Destroys a test suite.
- * @param suite the test suite to destroy
+ * Deallocates a test suite.
+ *
+ * @param suite the test suite to free
  */
 static inline void cx_test_suite_free(CxTestSuite* suite) {
+    if (suite == NULL) return;
     CxTestSet *l = suite->tests;
     while (l != NULL) {
         CxTestSet *e = l;
@@ -179,8 +173,10 @@
  * 
  * @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) {
     CxTestSet *t = (CxTestSet*) malloc(sizeof(CxTestSet));
     if (t) {
@@ -205,8 +201,9 @@
  * 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,
                                void *out_target, cx_write_func out_writer) {
     if (suite->name == NULL) {
@@ -233,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)
 
@@ -255,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.
  */
@@ -272,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; \
@@ -288,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")