From: brarcher Date: Sun, 16 Feb 2014 04:58:52 +0000 (+0000) Subject: Make check.h.in Doxygen friendly X-Git-Tag: 0.10.0~104 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=db263d3f25d43233ef66d70fdaee9d57263f187d;p=check Make check.h.in Doxygen friendly All prototypes and enums are now documented using javadoc. Doxygen is able to convert this file into a web page displaying Check's API. This will be used on Check's web page to display what API is available and when it was introduced. git-svn-id: svn+ssh://svn.code.sf.net/p/check/code/trunk@1113 64e312b2-a51f-0410-8e61-82d0ca0eb02a --- diff --git a/src/check.h.in b/src/check.h.in index 48130df..a8aa571 100644 --- a/src/check.h.in +++ b/src/check.h.in @@ -113,8 +113,10 @@ CK_CPPSTART #include -/* Used to create the linker script for hiding lib-local symbols. Shall - be put directly in front of the exported symbol. */ +/* + * Used to create the linker script for hiding lib-local symbols. Shall + * be put directly in front of the exported symbol. + */ #define CK_EXPORT /* @@ -127,7 +129,7 @@ CK_CPPSTART #endif /* check version numbers */ - + #define CHECK_MAJOR_VERSION (@CHECK_MAJOR_VERSION@) #define CHECK_MINOR_VERSION (@CHECK_MINOR_VERSION@) #define CHECK_MICRO_VERSION (@CHECK_MICRO_VERSION@) @@ -140,63 +142,183 @@ CK_DLL_EXP extern int CK_EXPORT check_micro_version; #define NULL ((void*)0) #endif -/* opaque type for a test case - - A TCase represents a test case. Create with tcase_create, free - with tcase_free. For the moment, test cases can only be run - through a suite +/** + * Type for a test case + * + * A TCase represents a test case. Create with tcase_create, free + * with tcase_free. For the moment, test cases can only be run + * through a suite */ typedef struct TCase TCase; -/* type for a test function */ +/** + * Type for a test function + */ typedef void (*TFun) (int); -/* type for a setup/teardown function */ +/** + * Type for a setup/teardown function + */ typedef void (*SFun) (void); -/* Opaque type for a test suite */ +/** + * Type for a test suite + */ typedef struct Suite Suite; -/* Creates a test suite with the given name */ +/** + * Creates a test suite with the given name. + * + * Create a suite, which will contain test cases. Once + * created, use suite_add_tcase() to add test cases. + * When finished, create a suite runner from the + * suite using srunner_create() + * + * @param name name of the suite + * + * @return suite + * + * @since 0.6.0 + */ CK_DLL_EXP Suite *CK_EXPORT suite_create(const char *name); -/* Determines whether a given test suite contains a case named after a - given string. */ +/** + * Determines whether a given test suite contains a case named after a + * given string. + * + * @param s suite to check + * @param tcname test case to look for + * + * @return 1 iff the given test case is within the given suite; + * 0 otherwise + * + * @since 0.9.9 + */ CK_DLL_EXP int CK_EXPORT suite_tcase(Suite * s, const char *tcname); -/* Add a test case to a suite */ +/** + * Add a test case to a suite + * + * @param s suite to add test case to + * @param tc test case to add to suite + * + * @since 0.6.0 + */ CK_DLL_EXP void CK_EXPORT suite_add_tcase(Suite * s, TCase * tc); -/* Create a test case */ +/** + * Create a test case. + * + * Once created, tests can be added with the tcase_add_test() + * function, and the test case assigned to a suite with the + * suite_add_tcase() function. + * + * @param name name of the test case + * + * @return test case containing no tests + * + * @since 0.6.0 + * */ CK_DLL_EXP TCase *CK_EXPORT tcase_create(const char *name); -/* Add a test function to a test case (macro version) */ +/** + * Add a test function to a test case + * + * @param tc test case to add test to + * @param tf test function to add to test case + * + * @since 0.6.0 + * */ #define tcase_add_test(tc,tf) tcase_add_test_raise_signal(tc,tf,0) -/* Add a test function with signal handling to a test case (macro version) */ +/** + * Add a test function with signal handling to a test case + * + * The added test is expected to terminate by throwing the given signal + * + * @param tc test case to add test to + * @param tf test function to add to test case + * @param signal expected signal for test function to throw in order for + * the test to be considered passing + * + * @since 0.9.2 + * */ #define tcase_add_test_raise_signal(tc,tf,signal) \ _tcase_add_test((tc),(tf),"" # tf "",(signal), 0, 0, 1) -/* Add a test function with an expected exit value to a test case (macro version) */ +/** + * Add a test function with an expected exit value to a test case + * + * The added test is expected to terminate by exiting with the given value + * + * @param tc test case to add test to + * @param tf test function to add to test case + * @param expected_exit_value exit value for test function to return in + * order for the test to be considered passing + * + * @since 0.9.7 + */ #define tcase_add_exit_test(tc, tf, expected_exit_value) \ _tcase_add_test((tc),(tf),"" # tf "",0,(expected_exit_value),0,1) -/* Add a looping test function to a test case (macro version) - - The test will be called in a for(i = s; i < e; i++) loop with each - iteration being executed in a new context. The loop variable 'i' is - available in the test. +/** + * Add a looping test function to a test case + * + * The test will be called in a for(i = s; i < e; i++) loop with each + * iteration being executed in a new context. The loop variable 'i' is + * available in the test. + * + * @param tc test case to add test to + * @param tf function to add to test case + * @param s starting index for value "i" in test + * @param e ending index for value "i" in test + * + * @since 0.9.4 */ #define tcase_add_loop_test(tc,tf,s,e) \ _tcase_add_test((tc),(tf),"" # tf "",0,0,(s),(e)) -/* Signal version of loop test. - FIXME: add a test case; this is untested as part of Check's tests. +/** + * Add a looping test function with signal handling to a test case + * + * The test will be called in a for(i = s; i < e; i++) loop with each + * iteration being executed in a new context. The loop variable 'i' is + * available in the test. + * + * The added test is expected to terminate by throwing the given signal + * + * @todo add a test case; this is untested as part of Check's tests. + * + * @param tc test case to add test to + * @param tf function to add to test case + * @param signal expected signal for test function to throw in order for + * the test to be considered passing + * @param s starting index for value "i" in test + * @param e ending index for value "i" in test + * + * @since 0.9.5 */ #define tcase_add_loop_test_raise_signal(tc,tf,signal,s,e) \ _tcase_add_test((tc),(tf),"" # tf "",(signal),0,(s),(e)) -/* allowed exit value version of loop test. */ +/** + * Add a looping test function with an expected exit value to a test case + * + * The test will be called in a for(i = s; i < e; i++) loop with each + * iteration being executed in a new context. The loop variable 'i' is + * available in the test. + * + * The added test is expected to terminate by exiting with the given value + * + * @param tc test case to add test to + * @param tf function to add to test case + * @param expected_exit_value exit value for test function to return in + * order for the test to be considered passing + * @param s starting index for value "i" in test + * @param e ending index for value "i" in test + * + * @since 0.9.7 + */ #define tcase_add_loop_exit_test(tc,tf,expected_exit_value,s,e) \ _tcase_add_test((tc),(tf),"" # tf "",0,(expected_exit_value),(s),(e)) @@ -208,76 +330,123 @@ CK_DLL_EXP void CK_EXPORT _tcase_add_test(TCase * tc, TFun tf, int allowed_exit_value, int start, int end); -/* Add unchecked fixture setup/teardown functions to a test case - - If unchecked fixture functions are run at the start and end of the - test case, and not before and after unit tests. Note that unchecked - setup/teardown functions are not run in a separate address space, - like test functions, and so must not exit or signal (e.g., - segfault) - - Also, when run in CK_NOFORK mode, unchecked fixture functions may - lead to different unit test behavior IF unit tests change data - setup by the fixture functions. -*/ +/** + * Add unchecked fixture setup/teardown functions to a test case + * + * If unchecked fixture functions are run at the start and end of the + * test case, and not before and after unit tests. Note that unchecked + * setup/teardown functions are not run in a separate address space, + * like test functions, and so must not exit or signal (e.g., + * segfault) + * + * Also, when run in CK_NOFORK mode, unchecked fixture functions may + * lead to different unit test behavior IF unit tests change data + * setup by the fixture functions. + * + * @param tc test case to add unchecked fixture setup/teardown to + * @param setup function to add to be executed before the test case; + * if NULL no setup function is added + * @param teardown function to add to be executed after the test case; + * if NULL no teardown function is added + * @since 0.8.0 + */ CK_DLL_EXP void CK_EXPORT tcase_add_unchecked_fixture(TCase * tc, SFun setup, SFun teardown); -/* Add fixture setup/teardown functions to a test case - - Checked fixture functions are run before and after unit - tests. Unlike unchecked fixture functions, checked fixture - functions are run in the same separate address space as the test - program, and thus the test function will survive signals or - unexpected exits in the fixture function. Also, IF the setup - function is idempotent, unit test behavior will be the same in - CK_FORK and CK_NOFORK modes. - - However, since fixture functions are run before and after each unit - test, they should not be expensive code. - +/** + * Add fixture setup/teardown functions to a test case + * + * Checked fixture functions are run before and after unit + * tests. Unlike unchecked fixture functions, checked fixture + * functions are run in the same separate address space as the test + * program, and thus the test function will survive signals or + * unexpected exits in the fixture function. Also, IF the setup + * function is idempotent, unit test behavior will be the same in + * CK_FORK and CK_NOFORK modes. + * + * However, since fixture functions are run before and after each unit + * test, they should not be expensive code. + * + * @param tc test case to add checked fixture setup/teardown to + * @param setup function to add to be executed before each unit test in + * the test case; if NULL no setup function is added + * @param teardown function to add to be executed after each unit test in + * the test case; if NULL no teardown function is added + * + * @since 0.8.0 */ CK_DLL_EXP void CK_EXPORT tcase_add_checked_fixture(TCase * tc, SFun setup, SFun teardown); -/* Set the timeout for all tests in a test case. A test that lasts longer - than the timeout (in seconds) will be killed and thus fail with an error. - The timeout can also be set globaly with the environment variable - CK_DEFAULT_TIMEOUT, the specific setting always takes precedence. -*/ +/** + * Set the timeout for all tests in a test case. + * + * A test that lasts longer than the timeout (in seconds) will be killed + * and thus fail with an error. + * + * If not set, the default timeout is one assigned at compile time. If + * the environment variable CK_DEFAULT_TIMEOUT is defined and no timeout + * is set, the value in the environment variable is used. + * + * @param tc test case to assign timeout to + * @param timeout to use, in seconds. If the value contains a decimal + * portion, but no high resolution timer is available, + * the value is rounded up to the nearest second. + * + * @since 0.9.2 + */ CK_DLL_EXP void CK_EXPORT tcase_set_timeout(TCase * tc, double timeout); /* Internal function to mark the start of a test function */ CK_DLL_EXP void CK_EXPORT tcase_fn_start(const char *fname, const char *file, int line); -/* Start a unit test with START_TEST(unit_name), end with END_TEST - One must use braces within a START_/END_ pair to declare new variables -*/ +/** + * Start a unit test with START_TEST(unit_name), end with END_TEST. + * + * One must use braces within a START_/END_ pair to declare new variables + * + * @since 0.6.0 + */ #define START_TEST(__testname)\ static void __testname (int _i CK_ATTRIBUTE_UNUSED)\ {\ tcase_fn_start (""# __testname, __FILE__, __LINE__); -/* End a unit test */ +/** + * End a unit test + * + * @since 0.6.0 + */ #define END_TEST } -/* Old check fail API, use new check fail API for newly written code. */ - -/* Fail the test case unless expr is false */ +/* + * Fail the test case unless expr is false + * + * This call is deprecated. + */ #define fail_unless ck_assert_msg -/* Fail the test case if expr is false */ -/* The space before the comma sign before ## is essential to be compatible - with gcc 2.95.3 and earlier. - FIXME: these macros may conflict with C89 if expr is - FIXME: strcmp (str1, str2) due to excessive string length. -*/ +/* + * Fail the test case if expr is false + * + * This call is deprecated. + * + * NOTE: The space before the comma sign before ## is essential to be compatible + * with gcc 2.95.3 and earlier. + * FIXME: these macros may conflict with C89 if expr is + * FIXME: strcmp (str1, str2) due to excessive string length. + */ #define fail_if(expr, ...)\ (expr) ? \ _ck_assert_failed(__FILE__, __LINE__, "Failure '"#expr"' occured" , ## __VA_ARGS__, NULL) \ : _mark_point(__FILE__, __LINE__) +/* + * Fail the test + * + * This call is deprecated. + */ #define fail ck_abort_msg /* @@ -297,20 +466,52 @@ CK_DLL_EXP void CK_EXPORT _ck_assert_failed(const char *file, int line, const char *expr, ...); #endif -/* New check fail API. */ +/** + * Fail the test if expression is false + * + * @param expr expression to evaluate + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.6 + */ +#define ck_assert(expr) ck_assert_msg(expr, NULL) -/* Fail the test case if expr is false */ /* The space before the comma sign before ## is essential to be compatible with gcc 2.95.3 and earlier. */ -#define ck_assert(C) ck_assert_msg(C, NULL) +/** + * Fail the test if the expression is false; print message on failure + * + * @param expr expression to evaluate + * @param ... message to print (in printf format) if expression is false + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.6 + */ #define ck_assert_msg(expr, ...) \ (expr) ? \ _mark_point(__FILE__, __LINE__) : \ _ck_assert_failed(__FILE__, __LINE__, "Assertion '"#expr"' failed" , ## __VA_ARGS__, NULL) -/* Always fail */ +/** + * Unconditionally fail the test + * + * @note Once called, the remaining of the test is aborted + * + * @since 0.9.6 + */ #define ck_abort() ck_abort_msg(NULL) +/** + * Unconditionally fail the test; print a message + * + * @param ... message to print (in printf format) + * + * @note Once called, the remaining of the test is aborted + * + * @since 0.9.6 + */ #define ck_abort_msg(...) _ck_assert_failed(__FILE__, __LINE__, "Failed" , ## __VA_ARGS__, NULL) /* Signed and unsigned integer comparsion macros with improved output compared to ck_assert(). */ @@ -320,11 +521,84 @@ CK_DLL_EXP void CK_EXPORT _ck_assert_failed(const char *file, int line, intmax_t _ck_y = (Y); \ ck_assert_msg(_ck_x OP _ck_y, "Assertion '"#X#OP#Y"' failed: "#X"==%jd, "#Y"==%jd", _ck_x, _ck_y); \ } while (0) + +/** + * Check two signed integers to determine if X==Y + * + * If not X==Y, the test fails. + * + * @param X signed integer + * @param Y signed integer to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.6 + */ #define ck_assert_int_eq(X, Y) _ck_assert_int(X, ==, Y) +/** + * Check two signed integers to determine if X!=Y + * + * If not X!=Y, the test fails. + * + * @param X signed integer + * @param Y signed integer to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.6 + */ #define ck_assert_int_ne(X, Y) _ck_assert_int(X, !=, Y) +/** + * Check two signed integers to determine if XY + * + * If not X>Y, the test fails. + * + * @param X signed integer + * @param Y signed integer to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.10 + */ #define ck_assert_int_gt(X, Y) _ck_assert_int(X, >, Y) +/** + * Check two signed integers to determine if X>=Y + * + * If not X>=Y, the test fails. + * + * @param X signed integer + * @param Y signed integer to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.10 + */ #define ck_assert_int_ge(X, Y) _ck_assert_int(X, >=, Y) #define _ck_assert_uint(X, OP, Y) do { \ @@ -332,11 +606,83 @@ CK_DLL_EXP void CK_EXPORT _ck_assert_failed(const char *file, int line, uintmax_t _ck_y = (Y); \ ck_assert_msg(_ck_x OP _ck_y, "Assertion '"#X#OP#Y"' failed: "#X"==%ju, "#Y"==%ju", _ck_x, _ck_y); \ } while (0) +/** + * Check two unsigned integers to determine if X==Y + * + * If not X==Y, the test fails. + * + * @param X signed integer + * @param Y signed integer to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.10 + */ #define ck_assert_uint_eq(X, Y) _ck_assert_uint(X, ==, Y) +/** + * Check two unsigned integers to determine if X!=Y + * + * If not X!=Y, the test fails. + * + * @param X signed integer + * @param Y signed integer to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.10 + */ #define ck_assert_uint_ne(X, Y) _ck_assert_uint(X, !=, Y) +/** + * Check two unsigned integers to determine if XY + * + * If not X>Y, the test fails. + * + * @param X signed integer + * @param Y signed integer to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.10 + */ #define ck_assert_uint_gt(X, Y) _ck_assert_uint(X, >, Y) +/** + * Check two unsigned integers to determine if X>=Y + * + * If not X>=Y, the test fails. + * + * @param X signed integer + * @param Y signed integer to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.10 + */ #define ck_assert_uint_ge(X, Y) _ck_assert_uint(X, >=, Y) /* String comparsion macros with improved output compared to ck_assert() */ @@ -348,11 +694,83 @@ CK_DLL_EXP void CK_EXPORT _ck_assert_failed(const char *file, int line, ck_assert_msg(0 OP strcmp(_ck_y, _ck_x), \ "Assertion '"#X#OP#Y"' failed: "#X"==\"%s\", "#Y"==\"%s\"", _ck_x, _ck_y); \ } while (0) +/** + * Check two strings to determine if 0==strcmp(X,Y) + * + * If not 0==strcmp(X,Y), the test fails. + * + * @param X string + * @param Y string to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.6 + */ #define ck_assert_str_eq(X, Y) _ck_assert_str(X, ==, Y) +/** + * Check two strings to determine if 0!=strcmp(X,Y) + * + * If not 0!=strcmp(X,Y), the test fails. + * + * @param X string + * @param Y string to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.6 + */ #define ck_assert_str_ne(X, Y) _ck_assert_str(X, !=, Y) +/** + * Check two strings to determine if 00) + * + * If not 0=0) + * + * If not 0<=strcmp(X,Y), the test fails. + * + * @param X string + * @param Y string to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.10 + */ #define ck_assert_str_le(X, Y) _ck_assert_str(X, <=, Y) +/** + * Check two strings to determine if 00) + * + * If not 0, Y) +/** + * Check two strings to determine if 0>=strcmp(X,Y) (e.g. strcmp(X,Y)<=0) + * + * If not 0>=strcmp(X,Y), the test fails. + * + * @param X string + * @param Y string to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.10 + */ #define ck_assert_str_ge(X, Y) _ck_assert_str(X, >=, Y) /* Pointer comparsion macros with improved output compared to ck_assert(). */ @@ -362,198 +780,519 @@ CK_DLL_EXP void CK_EXPORT _ck_assert_failed(const char *file, int line, const void* _ck_y = (Y); \ ck_assert_msg(_ck_x OP _ck_y, "Assertion '"#X#OP#Y"' failed: "#X"==%#x, "#Y"==%#x", _ck_x, _ck_y); \ } while (0) + +/** + * Check if two pointers are equal. + * + * If the two passed pointers are not equal, the test + * fails. + * + * @param X pointer + * @param Y pointer to compare against X + * + * @note If the check fails, the remaining of the test is aborted + * + * @since 0.9.10 + */ #define ck_assert_ptr_eq(X, Y) _ck_assert_ptr(X, ==, Y) + +/** + * Check if two pointers are not. + * + * If the two passed pointers are equal, the test fails. + * + * @param X pointer + * @param Y pointer to compare against X + * + * @since 0.9.10 + */ #define ck_assert_ptr_ne(X, Y) _ck_assert_ptr(X, !=, Y) -/* Mark the last point reached in a unit test - (useful for tracking down where a segfault, etc. occurs) +/** + * Mark the last point reached in a unit test. + * + * If the test throws a signal or exits, the location noted with the + * failure is the last location of a ck_assert*() or ck_abort() call. + * Use mark_point() to record intermediate locations (useful for tracking down + * crashes or exits). + * + * @since 0.6.0 */ #define mark_point() _mark_point(__FILE__,__LINE__) /* Non macro version of #mark_point */ CK_DLL_EXP void CK_EXPORT _mark_point(const char *file, int line); -/* Result of a test */ +/** + * Enum describing the possible results of a test */ enum test_result { - CK_TEST_RESULT_INVALID, /* Default value; should not encounter this */ - CK_PASS, /* Test passed */ - CK_FAILURE, /* Test completed but failed */ - CK_ERROR /* Test failed to complete + CK_TEST_RESULT_INVALID, /**< Default value; should not encounter this */ + CK_PASS, /**< Test passed */ + CK_FAILURE, /**< Test completed but failed */ + CK_ERROR /**< Test failed to complete (unexpected signal or non-zero early exit) */ }; -/* Specifies the how much output an SRunner should produce */ +/** + * Enum specifying the verbosity of output a SRunner should produce + */ enum print_output { - CK_SILENT, /* No output */ - CK_MINIMAL, /* Only summary output */ - CK_NORMAL, /* All failed tests */ - CK_VERBOSE, /* All tests */ - CK_ENV, /* Look at environment var */ + CK_SILENT, /**< No output */ + CK_MINIMAL, /**< Only summary output */ + CK_NORMAL, /**< All failed tests */ + CK_VERBOSE, /**< All tests */ + CK_ENV, /**< Look at environment var CK_VERBOSITY + for what verbosity to use, which can be + either "silent", "minimal", "normal", + or "verbose". If the environment variable + is not set, then CK_NORMAL will be used.*/ #if @ENABLE_SUBUNIT@ - CK_SUBUNIT, /* Run as a subunit child process */ + CK_SUBUNIT, /**< Run as a subunit child process */ #endif - CK_LAST + CK_LAST /**< Not a valid option */ }; -/* Holds state for a running of a test suite */ +/** + * Holds state for a running of a test suite + */ typedef struct SRunner SRunner; -/* Opaque type for a test failure */ +/** + * Opaque type for a test failure + */ typedef struct TestResult TestResult; -/* accessors for tr fields */ +/** + * Enum representing the types of contexts for a test + */ enum ck_result_ctx { - CK_CTX_INVALID, /* Default value; should not encounter this */ - CK_CTX_SETUP, - CK_CTX_TEST, - CK_CTX_TEARDOWN + CK_CTX_INVALID, /**< Default value; should not encounter this */ + CK_CTX_SETUP, /**< Setup before a test */ + CK_CTX_TEST, /**< Body of test itself */ + CK_CTX_TEARDOWN /**< Teardown after a test */ }; -/* Type of result */ +/** + * Retrieve type of result that the given test result represents. + * + * This is a member of test_result, and can represent a + * pass, failure, or error. + * + * @param tr test result to retrieve result from + * + * @return result of given test + * + * @since 0.6.0 + */ CK_DLL_EXP int CK_EXPORT tr_rtype(TestResult * tr); -/* Context in which the result occurred */ +/** + * Retrieve context in which the result occurred for the given test result. + * + * The types of contents include the test setup, teardown, or the + * body of the test itself. + * + * @param tr test result to retrieve context from + * + * @return context to which the given test result applies + * + * @since 0.8.0 + */ CK_DLL_EXP enum ck_result_ctx CK_EXPORT tr_ctx(TestResult * tr); -/* Failure message */ +/** + * Retrieve failure message from test result, if applicable. + * + * @return pointer to a message, if one exists. NULL otherwise. + * + * @since 0.6.0 + */ CK_DLL_EXP const char *CK_EXPORT tr_msg(TestResult * tr); -/* Line number at which failure occured */ +/** + * Retrieve line number at which a failure occured, if applicable. + * + * @return If the test resulted in a failure, returns the line number + * that the failure occured on; otherwise returns -1. + * + * @since 0.6.0 + */ CK_DLL_EXP int CK_EXPORT tr_lno(TestResult * tr); -/* File name at which failure occured */ +/** + * Retrieve file name at which a failure occured, if applicable. + * + * @return If the test resulted in a failure, returns a string + * containing the name of the file where the failure + * occurred; otherwise returns NULL. + * + * @since 0.6.0 + */ CK_DLL_EXP const char *CK_EXPORT tr_lfile(TestResult * tr); -/* Test case in which unit test was run */ +/** + * Retrieve test case name in which a failure occurred, if applicable. + * + * @return If the test resulted in a failure, returns a string + * containing the name of the test suite where the failure + * occurred; otherwise returns NULL. + * + * @since 0.6.0 + */ CK_DLL_EXP const char *CK_EXPORT tr_tcname(TestResult * tr); -/* Creates an SRunner for the given suite */ +/** + * Creates a suite runner for the given suite. + * + * Once created, additional suites can be added to the + * suite runner using srunner_add_suite(), and the suite runner can be + * run with srunner_run_all(). Once finished, the suite runner + * must be freed with srunner_free(). + * + * @param s suite to generate a suite runner for + * + * @return suite runner for the given suite + * + * @since 0.6.0 + */ CK_DLL_EXP SRunner *CK_EXPORT srunner_create(Suite * s); -/* Adds a Suite to an SRunner */ +/** + * Add an additional suite to a suite runner. + * + * The first suite in a suite runner is always added in srunner_create(). + * This call adds additional suites to a suite runner. + * + * @param sr suite runner to add the given suite + * @param s suite to add to the given suite runner + * + * @since 0.7.0 + */ CK_DLL_EXP void CK_EXPORT srunner_add_suite(SRunner * sr, Suite * s); -/* Frees an SRunner, all suites added to it and all contained test cases */ +/** + * Frees a suite runner, including all contained suite and test cases. + * + * This call is responsible for freeing all resources related to a + * suite runner and all contained suites and test cases. Suite and + * test cases need not be freed individually, as this call handles that. + * + * @param sr suite runner to free + * + * @since 0.6.0 + */ CK_DLL_EXP void CK_EXPORT srunner_free(SRunner * sr); - -/* Test running */ - -/* Runs an SRunner, printing results as specified (see enum print_output) */ +/** + * Runs a suite runner and all contained suite, printing results to + * stdout as specified by the print_mode. + * + * In addition to running all suites, if the suite runner has been + * configured to output to a log, that is also performed. + * + * Note that if the CK_RUN_CASE and/or CK_RUN_SUITE environment variables + * are defined, then only the named suite and/or test case is run. + * + * @param sr suite runner to run all suites from + * @param print_mode the verbosity in which to report results to stdout + * + * @since 0.6.0 + */ CK_DLL_EXP void CK_EXPORT srunner_run_all(SRunner * sr, enum print_output print_mode); -/* Runs an SRunner specifying test suite and test case by name, - printing results as specified (see enum print_output). A NULL - value means "any test suite" or "any test case". */ +/** + * Run a specific suite or test case from a suite runner, printing results + * to stdout as specified by the print_mode. + * + * In addition to running any applicable suites or test cases, if the + * suite runner has been configured to output to a log, that is also + * performed. + * + * @param sr suite runner where the given suite or test case must be + * @param sname suite name to run. A NULL means "any suite". + * @param tcname test case name to run. A NULL means "any test case" + * @param print_mode the verbosity in which to report results to stdout + * + * @since 0.9.9 + */ CK_DLL_EXP void CK_EXPORT srunner_run(SRunner * sr, const char *sname, const char *tcname, enum print_output print_mode); -/* Next functions are valid only after the suite has been - completely run, of course */ - -/* Number of failed tests in a run suite. Includes failures + errors */ +/** + * Retrieve the number of failed tests executed by a suite runner. + * + * This value represents both test failures and errors. + * + * @param sr suite runner to query for all failed tests + * + * @return number of test failures and errors found by the suite runner + * + * @since 0.6.1 + */ CK_DLL_EXP int CK_EXPORT srunner_ntests_failed(SRunner * sr); -/* Total number of tests run in a run suite */ +/** + * Retrieve the total number of tests run by a suite runner. + * + * @param sr suite runner to query for all tests run + * + * @return number of all tests run by the suite runner + * + * @since 0.6.1 + */ CK_DLL_EXP int CK_EXPORT srunner_ntests_run(SRunner * sr); -/* Return an array of results for all failures - - Number of failures is equal to srunner_nfailed_tests. Memory for - the array is malloc'ed and must be freed, but individual TestResults - must not -*/ +/** + * Return an array of results for all failures found by a suite runner. + * + * Number of results is equal to srunner_nfailed_tests(). + * + * Information about individual results can be queried using: + * tr_rtype(), tr_ctx(), tr_msg(), tr_lno(), tr_lfile(), and tr_tcname(). + * + * Memory is malloc'ed and must be freed; however free the entire structure + * instead of individual test cases. + * + * @param sr suite runner to retrieve results from + * + * @return array of TestResult objects + * + * @since 0.6.0 + */ CK_DLL_EXP TestResult **CK_EXPORT srunner_failures(SRunner * sr); -/* Return an array of results for all run tests - - Number of results is equal to srunner_ntests_run, and excludes - failures due to setup function failure. - - Memory is malloc'ed and must be freed, but individual TestResults - must not +/** + * Return an array of results for all tests run by a suite runner. + * + * Number of results is equal to srunner_ntests_run(), and excludes + * failures due to setup function failure. + * + * Information about individual results can be queried using: + * tr_rtype(), tr_ctx(), tr_msg(), tr_lno(), tr_lfile(), and tr_tcname(). + * + * Memory is malloc'ed and must be freed; however free the entire structure + * instead of individual test cases. + * + * @param sr suite runner to retrieve results from + * + * @return array of TestResult objects + * + * @since 0.6.1 */ CK_DLL_EXP TestResult **CK_EXPORT srunner_results(SRunner * sr); - -/* Printing */ - -/* Print the results contained in an SRunner */ +/** + * Print the results contained in an SRunner to stdout. + * + * @param sr suite runner to print results for to stdout + * @param print_mode the print_output (verbosity) to use to report + * the result + * + * @since 0.7.0 + */ CK_DLL_EXP void CK_EXPORT srunner_print(SRunner * sr, enum print_output print_mode); - -/* Set a log file to which to write during test running. - - Log file setting is an initialize only operation -- it should be - done immediatly after SRunner creation, and the log file can't be - changed after being set. +/** + * Set the suite runner to output the result in log format to the + * given file. + * + * Note: log file setting is an initialize only operation -- it should + * be done immediatly after SRunner creation, and the log file can't be + * changed after being set. + * + * This setting does not conflict with the other log output types; + * all logging types can occur concurrently if configured. + * + * @param sr suite runner to log results of in log format + * @param fname file name to output log results to + * + * @since 0.7.1 */ CK_DLL_EXP void CK_EXPORT srunner_set_log(SRunner * sr, const char *fname); -/* Does the SRunner have a log file? */ +/** + * Checks if the suite runner is assigned a file for log output. + * + * @param sr suite runner to check + * + * @return 1 iff the suite runner currently is configured to output + * in log format; 0 otherwise + * + * @since 0.7.1 + */ CK_DLL_EXP int CK_EXPORT srunner_has_log(SRunner * sr); -/* Return the name of the log file, or NULL if none */ +/** + * Retrieves the name of the currently assigned file + * for log output, if any exists. + * + * @return the name of the log file, or NULL if none is configured + * + * @since 0.7.1 + */ CK_DLL_EXP const char *CK_EXPORT srunner_log_fname(SRunner * sr); -/* Set a xml file to which to write during test running. - - XML file setting is an initialize only operation -- it should be - done immediatly after SRunner creation, and the XML file can't be - changed after being set. +/** + * Set the suite runner to output the result in XML format to the + * given file. + * + * Note: XML file setting is an initialize only operation -- it should + * be done immediatly after SRunner creation, and the XML file can't be + * changed after being set. + * + * This setting does not conflict with the other log output types; + * all logging types can occur concurrently if configured. + * + * @param sr suite runner to log results of in XML format + * @param fname file name to output XML results to + * + * @since 0.9.1 */ CK_DLL_EXP void CK_EXPORT srunner_set_xml(SRunner * sr, const char *fname); -/* Does the SRunner have an XML log file? */ +/** + * Checks if the suite runner is assigned a file for XML output. + * + * @param sr suite runner to check + * + * @return 1 iff the suite runner currently is configured to output + * in XML format; 0 otherwise + * + * @since 0.9.1 + */ CK_DLL_EXP int CK_EXPORT srunner_has_xml(SRunner * sr); -/* Return the name of the XML file, or NULL if none */ +/** + * Retrieves the name of the currently assigned file + * for XML output, if any exists. + * + * @return the name of the XML file, or NULL if none is configured + * + * @since 0.9.1 + */ CK_DLL_EXP const char *CK_EXPORT srunner_xml_fname(SRunner * sr); -/* Set a tap file to which to write during test running. - - Log file setting is an initialize only operation -- it should be - done immediatly after SRunner creation, and the log file can't be - changed after being set. +/** + * Set the suite runner to output the result in TAP format to the + * given file. + * + * Note: TAP file setting is an initialize only operation -- it should + * be done immediatly after SRunner creation, and the TAP file can't be + * changed after being set. + * + * This setting does not conflict with the other log output types; + * all logging types can occur concurrently if configured. + * + * @param sr suite runner to log results of in TAP format + * @param fname file name to output TAP results to + * + * @since 0.9.12 */ CK_DLL_EXP void CK_EXPORT srunner_set_tap(SRunner * sr, const char *fname); -/* Does the SRunner have a tap file? */ +/** + * Checks if the suite runner is assigned a file for TAP output. + * + * @param sr suite runner to check + * + * @return 1 iff the suite runner currently is configured to output + * in TAP format; 0 otherwise + * + * @since 0.9.12 + */ CK_DLL_EXP int CK_EXPORT srunner_has_tap(SRunner * sr); -/* Return the name of the tap file, or NULL if none */ +/** + * Retrieves the name of the currently assigned file + * for TAP output, if any exists. + * + * @return the name of the TAP file, or NULL if none is configured + * + * @since 0.9.12 + */ CK_DLL_EXP const char *CK_EXPORT srunner_tap_fname(SRunner * sr); - -/* Control forking */ +/** + * Enum describing the current fork usage. + * + * @since 0.8.0 + */ enum fork_status { - CK_FORK_GETENV, /* look in the environment for CK_FORK */ - CK_FORK, /* call fork to run tests */ - CK_NOFORK /* don't call fork */ + CK_FORK_GETENV, /**< look in the environment for CK_FORK */ + CK_FORK, /**< call fork to run tests */ + CK_NOFORK /**< don't call fork */ }; -/* Get the current fork status */ +/** + * Retrieve the current fork status for the given suite runner + * + * @param sr suite runner to check fork status of + * + * @since 0.8.0 + */ CK_DLL_EXP enum fork_status CK_EXPORT srunner_fork_status(SRunner * sr); -/* Set the current fork status */ +/** + * Set the fork status for a given suite runner. + * + * The default fork status is CK_FORK_GETENV, which will look + * for the CK_FORK environment variable, which can be set to + * "yes" or "no". If the environment variable is not present, + * CK_FORK will be used if fork() is available on the system, + * otherwise CK_NOFORK is used. + * + * If set to CK_FORK or CK_NOFORK, the environment variable + * if defined is ignored. + * + * @param sr suite runner to assign the fork status to + * @param fstat fork status to assign + * + * @since 0.8.0 + */ CK_DLL_EXP void CK_EXPORT srunner_set_fork_status(SRunner * sr, enum fork_status fstat); -/* Fork in a test and make sure messaging and tests work. */ +/** + * Invoke fork() during a test and assign the child to the same + * process group that the rest of the test case uses. + * + * One can invoke fork() directly during a test; however doing so + * may not guarantee that any children processes are destroyed once + * the test finishes. Once a test has completed, all processes in + * the process group will be killed; using this wrapper will prevent + * orphan processes. + * + * @return On success, the PID of the child process is returned in + * the parent, and 0 is returned in the child. On failure, + * an error will be printed and exit() invoked. + * + * @since 0.9.3 + */ CK_DLL_EXP pid_t CK_EXPORT check_fork(void); -/* Wait for the pid and exit. If pid is zero, just exit. */ +/** + * Wait for the pid and exit. + * + * This is to be used in conjunction with check_fork(). When called, + * will wait for the given process to terminate. If the process + * exited without error, exit(EXIT_SUCCESS) is invoked; otherwise + * exit(EXIT_FAILURE) is invoked. + * + * @param pid process to wait for, created by check_fork() + * + * @since 0.9.3 + */ CK_DLL_EXP void CK_EXPORT check_waitpid_and_exit(pid_t pid) CK_ATTRIBUTE_NORETURN; -#ifdef __cplusplus +#ifdef __cplusplus CK_CPPEND #endif