ucx: comparison src/cx/test.h

-:ef4a6cb318ec
+:4f6346a7dd78
 *
 * Usage of this test framework:
 *
 * **** 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()
 * }
 *
 * CX_TEST(function_name) {
 *     // tests with CX_TEST_ASSERT() and/or
 *     // calls with CX_TEST_CALL_SUBROUTINE() here
 *   }
 *   // 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().
 *
 * @author Mike Becker
 * <code>__func__</code>.
 */
 #define __FUNCTION__ __func__
 #endif
-//
 #if !defined(__clang__) && __GNUC__ > 3
 #pragma GCC diagnostic ignored "-Wclobbered"
 #endif
 /** Type for the CxTestSuite. */
 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. */
 typedef struct CxTestSet CxTestSet;
 /**
 * Registers a test function with the specified test suite.
 *
 * @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) {
 /**
 * 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) {
 out_writer(total, 1, len, out_target);
 }
 /**
 * Runs a test suite and writes the test log to the specified FILE stream.
-* @param suite the test suite to run
+* @param suite (@c CxTestSuite*) the test suite to run
-* @param file the target file to write the output to
+* @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)
 /**
 * Macro for a #CxTest function header.
 */
 #define CX_TEST(name) void name(CxTestSuite* _suite_,void *_output_, cx_write_func _writefnc_)
 /**
 * 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.
 */
 #define CX_TEST_DO _writefnc_("Running ", 1, 8, _output_);\
 _writefnc_(__FUNCTION__, 1, strlen(__FUNCTION__), _output_);\
 /**
 * Checks a test assertion.
 * 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
-* @param message the message that shall be printed out on failure
+* @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; \
 _writefnc_(_assert_msg_, 1, strlen(_assert_msg_), _output_); \
 _writefnc_(".\n", 1, 2, _output_); \
 /**
 * Checks a test assertion.
 * 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")
 /**
 * Macro for a test subroutine function header.

Mercurial > hg > ucx / file comparison

comparison: src/cx/test.h

src/cx/test.h