luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-11-09 12:33:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

testutils: Some more docs tweaks

Browse Source 
These changes are largely to bring the style closer to
what is recommended in

https://developer.gnome.org/documentation/guidelines/devel-docs.html
This commit is contained in:
Matthias Clasen
2024-11-15 13:33:20 -05:00
parent ff22358396
commit 164486b7ea
2 changed files with 165 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files

289
glib/gtestutils.c
View File

@@ -71,9 +71,9 @@
/** /**
* g_test_initialized: * g_test_initialized:
* *
* Returns `TRUE` if [func@GLib.test_init] has been called. * Returns true if [func@GLib.test_init] has been called.
* *
* Returns: `TRUE` if [func@GLib.test_init] has been called. * Returns: true if [func@GLib.test_init] has been called.
* *
* Since: 2.36 * Since: 2.36
*/ */
@@ -81,7 +81,7 @@
/** /**
* g_test_quick: * g_test_quick:
* *
* Returns `TRUE` if tests are run in quick mode. * Returns true if tests are run in quick mode.
* *
* Tests are always run in slow mode or in fast mode; there is no "medium speed". * Tests are always run in slow mode or in fast mode; there is no "medium speed".
* *
@@ -89,13 +89,13 @@
* [func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough` * [func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough`
* can be used to change this. * can be used to change this.
* *
* Returns: `TRUE` if in quick mode * Returns: true if in quick mode
*/ */
/** /**
* g_test_slow: * g_test_slow:
* *
* Returns `TRUE` if tests are run in slow mode. * Returns true if tests are run in slow mode.
* *
* Tests are always run in slow mode or in fast mode; there is no "medium speed". * Tests are always run in slow mode or in fast mode; there is no "medium speed".
* *
@@ -103,13 +103,13 @@
* [func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough` * [func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough`
* can be used to change this. * can be used to change this.
* *
* Returns: `TRUE` if in slow mode * Returns: true if in slow mode
*/ */
/** /**
* g_test_thorough: * g_test_thorough:
* *
* Returns `TRUE` if tests are run in thorough mode. * Returns true if tests are run in thorough mode.
* *
* Thorough mode is equivalent to slow mode. * Thorough mode is equivalent to slow mode.
* *
@@ -117,25 +117,25 @@
* [func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough` * [func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough`
* can be used to change this. * can be used to change this.
* *
* Returns: `TRUE` if in thorough mode * Returns: true if in thorough mode
*/ */
/** /**
* g_test_perf: * g_test_perf:
* *
* Returns `TRUE` if tests are run in performance mode. * Returns true if tests are run in performance mode.
* *
* By default, tests are run in quick mode. In tests that use * By default, tests are run in quick mode. In tests that use
* [func@GLib.test_init], the option `-m perf` enables performance tests, while * [func@GLib.test_init], the option `-m perf` enables performance tests, while
* `-m quick` disables them. * `-m quick` disables them.
* *
* Returns: `TRUE` if in performance mode * Returns: true if in performance mode
*/ */
/** /**
* g_test_undefined: * g_test_undefined:
* *
* Returns `TRUE` if tests may provoke assertions and other formally-undefined * Returns true if tests may provoke assertions and other formally-undefined
* behaviour, to verify that appropriate warnings are given. * behaviour, to verify that appropriate warnings are given.
* *
* This might, in some cases, be useful to turn this off (e.g. if running tests * This might, in some cases, be useful to turn this off (e.g. if running tests
@@ -149,33 +149,33 @@
* [AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) * [AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer)
* is enabled, the default changes to not exercising undefined behaviour. * is enabled, the default changes to not exercising undefined behaviour.
* *
* Returns: `TRUE` if tests may provoke programming errors * Returns: true if tests may provoke programming errors
*/ */
/** /**
* g_test_verbose: * g_test_verbose:
* *
* Returns `TRUE` if tests are run in verbose mode. * Returns true if tests are run in verbose mode.
* *
* In tests that use [func@GLib.test_init], the option `--verbose` enables this, * In tests that use [func@GLib.test_init], the option `--verbose` enables this,
* while `-q` or `--quiet` disables it. * while `-q` or `--quiet` disables it.
* *
* The default is neither verbose nor quiet. * The default is neither verbose nor quiet.
* *
* Returns: `TRUE` if in verbose mode * Returns: true if in verbose mode
*/ */
/** /**
* g_test_quiet: * g_test_quiet:
* *
* Returns `TRUE` if tests are run in quiet mode. * Returns true if tests are run in quiet mode.
* *
* In tests that use [func@GLib.test_init], the option `-q` or `--quiet` enables * In tests that use [func@GLib.test_init], the option `-q` or `--quiet` enables
* this, while `--verbose` disables it. * this, while `--verbose` disables it.
* *
* The default is neither verbose nor quiet. * The default is neither verbose nor quiet.
* *
* Returns: `TRUE` if in quiet mode * Returns: true if in quiet mode
*/ */
/** /**
@@ -234,7 +234,7 @@
* be undefined behaviour, like inputs that fail a [func@GLib.return_if_fail] * be undefined behaviour, like inputs that fail a [func@GLib.return_if_fail]
* check. In these situations you should skip the entire test, including the * check. In these situations you should skip the entire test, including the
* call to [func@GLib.test_trap_subprocess], unless [func@GLib.test_undefined] * call to [func@GLib.test_trap_subprocess], unless [func@GLib.test_undefined]
* returns `TRUE` to indicate that undefined behaviour may be tested. * returns true to indicate that undefined behaviour may be tested.
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -276,7 +276,7 @@
* to be undefined behaviour, like code that hits a [func@GLib.assert] or * to be undefined behaviour, like code that hits a [func@GLib.assert] or
* [func@GLib.error]. In these situations you should skip the entire test, * [func@GLib.error]. In these situations you should skip the entire test,
* including the call to [func@GLib.test_trap_subprocess], unless * including the call to [func@GLib.test_trap_subprocess], unless
* [func@GLib.test_undefined] returns `TRUE` to indicate that undefined * [func@GLib.test_undefined] returns true to indicate that undefined
* behaviour may be tested. * behaviour may be tested.
* *
* Since: 2.16 * Since: 2.16
@@ -414,10 +414,10 @@
/** /**
* g_assert_cmpstr: * g_assert_cmpstr:
* @s1: a string (may be `NULL`) * @s1: (nullable): a string
* @cmp: The comparison operator to use. * @cmp: the comparison operator to use.
* One of `==`, `!=`, `<`, `>`, `<=`, `>=`. * One of `==`, `!=`, `<`, `>`, `<=`, `>=`
* @s2: another string (may be `NULL`) * @s2: (nullable): another string
* *
* Debugging macro to compare two strings. * Debugging macro to compare two strings.
* *
@@ -439,8 +439,8 @@
/** /**
* g_assert_cmpstrv: * g_assert_cmpstrv:
* @strv1: (nullable): a string array (may be `NULL`) * @strv1: (nullable): a string array
* @strv2: (nullable): another string array (may be `NULL`) * @strv2: (nullable): another string array
* *
* Debugging macro to check if two `NULL`-terminated string arrays (i.e. 2 * Debugging macro to check if two `NULL`-terminated string arrays (i.e. 2
* `GStrv`) are equal. * `GStrv`) are equal.
@@ -466,8 +466,8 @@
/** /**
* g_assert_cmpint: * g_assert_cmpint:
* @n1: an integer * @n1: an integer
* @cmp: The comparison operator to use. * @cmp: the comparison operator to use.
* One of `==`, `!=`, `<`, `>`, `<=`, `>=`. * One of `==`, `!=`, `<`, `>`, `<=`, `>=`
* @n2: another integer * @n2: another integer
* *
* Debugging macro to compare two integers. * Debugging macro to compare two integers.
@@ -483,8 +483,8 @@
/** /**
* g_assert_cmpuint: * g_assert_cmpuint:
* @n1: an unsigned integer * @n1: an unsigned integer
* @cmp: The comparison operator to use. * @cmp: the comparison operator to use.
* One of `==`, `!=`, `<`, `>`, `<=`, `>=`. * One of `==`, `!=`, `<`, `>`, `<=`, `>=`
* @n2: another unsigned integer * @n2: another unsigned integer
* *
* Debugging macro to compare two unsigned integers. * Debugging macro to compare two unsigned integers.
@@ -500,8 +500,8 @@
/** /**
* g_assert_cmphex: * g_assert_cmphex:
* @n1: an unsigned integer * @n1: an unsigned integer
* @cmp: The comparison operator to use. * @cmp: the comparison operator to use.
* One of `==`, `!=`, `<`, `>`, `<=`, `>=`. * One of `==`, `!=`, `<`, `>`, `<=`, `>=`
* @n2: another unsigned integer * @n2: another unsigned integer
* *
* Debugging macro to compare to unsigned integers. * Debugging macro to compare to unsigned integers.
@@ -515,8 +515,8 @@
/** /**
* g_assert_cmpfloat: * g_assert_cmpfloat:
* @n1: a floating point number * @n1: a floating point number
* @cmp: The comparison operator to use. * @cmp: the comparison operator to use.
* One of `==`, `!=`, `<`, `>`, `<=`, `>=`. * One of `==`, `!=`, `<`, `>`, `<=`, `>=`
* @n2: another floating point number * @n2: another floating point number
* *
* Debugging macro to compare two floating point numbers. * Debugging macro to compare two floating point numbers.
@@ -567,9 +567,9 @@
/** /**
* g_assert_cmpmem: * g_assert_cmpmem:
* @m1: (nullable): pointer to a buffer * @m1: (nullable): pointer to a buffer
* @l1: length of @m1 * @l1: length of @m1 in bytes
* @m2: (nullable): pointer to another buffer * @m2: (nullable): pointer to another buffer
* @l2: length of @m2 * @l2: length of @m2 in bytes
* *
* Debugging macro to compare memory regions. * Debugging macro to compare memory regions.
* *
@@ -611,7 +611,7 @@
/** /**
* g_assert_no_error: * g_assert_no_error:
* @err: a `GError`, possibly `NULL` * @err: (nullable) a `GError`
* *
* Debugging macro to check that a [struct@GLib.Error] is not set. * Debugging macro to check that a [struct@GLib.Error] is not set.
* *
@@ -625,7 +625,7 @@
/** /**
* g_assert_error: * g_assert_error:
* @err: a `GError`, possibly `NULL` * @err: (nullable): a `GError`
* @dom: the expected error domain (a `GQuark`) * @dom: the expected error domain (a `GQuark`)
* @c: the expected error code * @c: the expected error code
* *
@@ -1153,7 +1153,7 @@ g_test_log (GTestLogType lbit,
/** /**
* g_test_disable_crash_reporting: * g_test_disable_crash_reporting:
* *
* Attempt to disable system crash reporting infrastructure. * Attempts to disable system crash reporting infrastructure.
* *
* This function should be called before exercising code paths that are * This function should be called before exercising code paths that are
* expected or intended to crash, to avoid wasting resources in system-wide * expected or intended to crash, to avoid wasting resources in system-wide
@@ -1626,15 +1626,14 @@ test_rm_isolate_dirs (void)
/** /**
* g_test_init: * g_test_init:
* @argc: Address of the @argc parameter of the main() function. * @argc: address of the @argc parameter of `main()`
* Changed if any arguments were handled. * @argv: address of the @argv parameter of `main()`
* @argv: Address of the @argv parameter of main(). * @...: `NULL`-terminated list of special options
* Any parameters understood by g_test_init() are stripped before return.
* @...: `NULL`-terminated list of special options.
* *
* Initialize the GLib testing framework, e.g. by seeding the test random * Initializes the GLib testing framework.
* number generator and the program name, and parsing test related commandline *
* args. * This includes seeding the test random number generator,
* setting the program name, and parsing test-related commandline args.
* *
* This should be called before calling any other `g_test_*()` functions. * This should be called before calling any other `g_test_*()` functions.
* *
@@ -1667,6 +1666,8 @@ test_rm_isolate_dirs (void)
* *
* - `--debug-log`: Debug test logging output. * - `--debug-log`: Debug test logging output.
* *
* Any parsed arguments are removed from @argv, and @argc is adjust accordingly.
*
* The following options are supported: * The following options are supported:
* *
* - `G_TEST_OPTION_NO_PRGNAME`: Causes g_test_init() to not call * - `G_TEST_OPTION_NO_PRGNAME`: Causes g_test_init() to not call
@@ -1677,7 +1678,7 @@ test_rm_isolate_dirs (void)
* - `G_TEST_OPTION_NONFATAL_ASSERTIONS`: This has the same effect as * - `G_TEST_OPTION_NONFATAL_ASSERTIONS`: This has the same effect as
* [func@GLib.test_set_nonfatal_assertions]. Since 2.84 * [func@GLib.test_set_nonfatal_assertions]. Since 2.84
* *
* Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined, g_test_init() * Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined, `g_test_init()`
* will print an error and exit. This is to prevent no-op tests from being executed, * will print an error and exit. This is to prevent no-op tests from being executed,
* as [func@GLib.assert] is commonly (erroneously) used in unit tests, and is a no-op * as [func@GLib.assert] is commonly (erroneously) used in unit tests, and is a no-op
* when compiled with `G_DISABLE_ASSERT`. Ensure your tests are compiled without * when compiled with `G_DISABLE_ASSERT`. Ensure your tests are compiled without
@@ -1942,7 +1943,7 @@ test_run_seed (const gchar *rseed)
/** /**
* g_test_rand_int: * g_test_rand_int:
* *
* Get a reproducible random integer number. * Gets a reproducible random integer number.
* *
* The random numbers generated by the g_test_rand_*() family of functions * The random numbers generated by the g_test_rand_*() family of functions
* change with every new test program start, unless the --seed option is * change with every new test program start, unless the --seed option is
@@ -1952,7 +1953,7 @@ test_run_seed (const gchar *rseed)
* reseeded, to avoid dependencies between tests and to make --seed * reseeded, to avoid dependencies between tests and to make --seed
* effective for all test cases. * effective for all test cases.
* *
* Returns: a random number from the seeded random number generator. * Returns: a random number from the seeded random number generator
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -1973,11 +1974,11 @@ g_test_rand_int (void)
* @begin: the minimum value returned by this function * @begin: the minimum value returned by this function
* @end: the smallest value not to be returned by this function * @end: the smallest value not to be returned by this function
* *
* Get a reproducible random integer number out of a specified range. * Gets a reproducible random integer number out of a specified range.
* *
* See [func@GLib.test_rand_int] for details on test case random numbers. * See [func@GLib.test_rand_int] for details on test case random numbers.
* *
* Returns: a number with @begin <= number < @end. * Returns: a number with @begin <= number < @end
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -1997,11 +1998,11 @@ g_test_rand_int_range (gint32 begin,
/** /**
* g_test_rand_double: * g_test_rand_double:
* *
* Get a reproducible random floating point number. * Gets a reproducible random floating point number.
* *
* See [func@GLib.test_rand_int] for details on test case random numbers. * See [func@GLib.test_rand_int] for details on test case random numbers.
* *
* Returns: a random number from the seeded random number generator. * Returns: a random number from the seeded random number generator
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -2022,11 +2023,11 @@ g_test_rand_double (void)
* @range_start: the minimum value returned by this function * @range_start: the minimum value returned by this function
* @range_end: the minimum value not returned by this function * @range_end: the minimum value not returned by this function
* *
* Get a reproducible random floating point number out of a specified range. * Gets a reproducible random floating point number out of a specified range.
* *
* See [func@GLib.test_rand_int] for details on test case random numbers. * See [func@GLib.test_rand_int] for details on test case random numbers.
* *
* Returns: a number with @range_start <= number < @range_end. * Returns: a number with @range_start <= number < @range_end
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -2046,7 +2047,7 @@ g_test_rand_double_range (double range_start,
/** /**
* g_test_timer_start: * g_test_timer_start:
* *
* Start a timing test. * Starts a timing test.
* *
* Call [func@GLib.test_timer_elapsed] when the task is supposed * Call [func@GLib.test_timer_elapsed] when the task is supposed
* to be done. Call this function again to restart the timer. * to be done. Call this function again to restart the timer.
@@ -2065,10 +2066,10 @@ g_test_timer_start (void)
/** /**
* g_test_timer_elapsed: * g_test_timer_elapsed:
* *
* Get the number of seconds since the last start of the timer with * Gets the number of seconds since the last start of the timer with
* [func@GLib.test_timer_start]. * [func@GLib.test_timer_start].
* *
* Returns: the time since the last start of the timer in seconds, as a double * Returns: the time since the last start of the timer in seconds
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -2082,9 +2083,9 @@ g_test_timer_elapsed (void)
/** /**
* g_test_timer_last: * g_test_timer_last:
* *
* Report the last result of [func@GLib.test_timer_elapsed]. * Reports the last result of [func@GLib.test_timer_elapsed].
* *
* Returns: the last result of [func@GLib.test_timer_elapsed], as a double * Returns: the last result of [func@GLib.test_timer_elapsed]
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -2098,9 +2099,9 @@ g_test_timer_last (void)
* g_test_minimized_result: * g_test_minimized_result:
* @minimized_quantity: the reported value * @minimized_quantity: the reported value
* @format: the format string of the report message * @format: the format string of the report message
* @...: arguments to pass to the printf() function * @...: printf-like arguments to @format
* *
* Report the result of a performance or measurement test. * Reports the result of a performance or measurement test.
* *
* The test should generally strive to minimize the reported * The test should generally strive to minimize the reported
* quantities (smaller values are better than larger ones), * quantities (smaller values are better than larger ones),
@@ -2130,9 +2131,9 @@ g_test_minimized_result (double minimized_quantity,
* g_test_maximized_result: * g_test_maximized_result:
* @maximized_quantity: the reported value * @maximized_quantity: the reported value
* @format: the format string of the report message * @format: the format string of the report message
* @...: arguments to pass to the printf() function * @...: printf-like arguments to @format
* *
* Report the result of a performance or measurement test. * Reports the result of a performance or measurement test.
* *
* The test should generally strive to maximize the reported * The test should generally strive to maximize the reported
* quantities (larger values are better than smaller ones), * quantities (larger values are better than smaller ones),
@@ -2163,7 +2164,7 @@ g_test_maximized_result (double maximized_quantity,
* @format: the format string * @format: the format string
* @...: printf-like arguments to @format * @...: printf-like arguments to @format
* *
* Add a message to the test report. * Adds a message to the test report.
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -2186,7 +2187,7 @@ g_test_message (const char *format,
* g_test_bug_base: * g_test_bug_base:
* @uri_pattern: the base pattern for bug URIs * @uri_pattern: the base pattern for bug URIs
* *
* Specify the base URI for bug reports. * Specifies the base URI for bug reports.
* *
* The base URI is used to construct bug report messages for * The base URI is used to construct bug report messages for
* [func@GLib.test_message] when [func@GLib.test_bug] is called. * [func@GLib.test_message] when [func@GLib.test_bug] is called.
@@ -2214,19 +2215,19 @@ g_test_bug_base (const char *uri_pattern)
* g_test_bug: * g_test_bug:
* @bug_uri_snippet: Bug specific bug tracker URI or URI portion. * @bug_uri_snippet: Bug specific bug tracker URI or URI portion.
* *
* This function adds a message to test reports that * Adds a message to test reports that associates a bug URI with a test case.
* associates a bug URI with a test case.
* *
* Bug URIs are constructed from a base URI set with [func@GLib.test_bug_base] * Bug URIs are constructed from a base URI set with [func@GLib.test_bug_base]
* and @bug_uri_snippet. If [func@GLib.test_bug_base] has not been called, it is * and @bug_uri_snippet. If [func@GLib.test_bug_base] has not been called, it is
* assumed to be the empty string, so a full URI can be provided to * assumed to be the empty string, so a full URI can be provided to
* [func@GLib.test_bug] instead. * [func@GLib.test_bug] instead.
* *
* See also [func@GLib.test_summary].
*
* Since GLib 2.70, the base URI is not prepended to @bug_uri_snippet * Since GLib 2.70, the base URI is not prepended to @bug_uri_snippet
* if it is already a valid URI. * if it is already a valid URI.
* *
* Since: 2.16 * Since: 2.16
* See also: [func@GLib.test_summary]
*/ */
void void
g_test_bug (const char *bug_uri_snippet) g_test_bug (const char *bug_uri_snippet)
@@ -2259,15 +2260,13 @@ g_test_bug (const char *bug_uri_snippet)
/** /**
* g_test_summary: * g_test_summary:
* @summary: One or two sentences summarising what the test checks, and how it * @summary: summary of the test purpose
* checks it.
* *
* Set the summary for a test, which describes what the test checks, and how it * Sets the summary for a test.
* goes about checking it.
* *
* This may be included in test report output, and is useful documentation for * This may be included in test report output, and is useful documentation for
* anyone reading the source code or modifying a test in future. It must be a * anyone reading the source code or modifying a test in future. It must be a
* single line. * single line, and it should summarise what the test checks, and how.
* *
* This should be called at the top of a test function. * This should be called at the top of a test function.
* *
@@ -2283,8 +2282,9 @@ g_test_bug (const char *bug_uri_snippet)
* } * }
* ]| * ]|
* *
* See also [func@GLib.test_bug].
*
* Since: 2.62 * Since: 2.62
* See also: [func@GLib.test_bug]
*/ */
void void
g_test_summary (const char *summary) g_test_summary (const char *summary)
@@ -2299,9 +2299,9 @@ g_test_summary (const char *summary)
/** /**
* g_test_get_root: * g_test_get_root:
* *
* Get the toplevel test suite for the test path API. * Gets the toplevel test suite for the test path API.
* *
* Returns: the toplevel `GTestSuite` * Returns: the toplevel test suite
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -2321,8 +2321,9 @@ g_test_get_root (void)
/** /**
* g_test_run: * g_test_run:
* *
* Runs all tests under the toplevel suite which can be retrieved * Runs all tests under the toplevel suite.
* with [func@GLib.test_get_root]. *
* The toplevel suite can be retrieved with [func@GLib.test_get_root].
* *
* Similar to [func@GLib.test_run_suite], the test cases to be run are * Similar to [func@GLib.test_run_suite], the test cases to be run are
* filtered according to test path arguments (`-p testpath` and `-s testpath`) * filtered according to test path arguments (`-p testpath` and `-s testpath`)
@@ -2421,7 +2422,7 @@ out:
* @data_test: (scope async): the actual test function * @data_test: (scope async): the actual test function
* @data_teardown: (scope async): the function to teardown the fixture data * @data_teardown: (scope async): the function to teardown the fixture data
* *
* Create a new [struct@GLib.TestCase], named @test_name. * Creates a new [struct@GLib.TestCase].
* *
* This API is fairly low level, and calling [func@GLib.test_add] or * This API is fairly low level, and calling [func@GLib.test_add] or
* [func@GLib.test_add_func] is preferable. * [func@GLib.test_add_func] is preferable.
@@ -2439,7 +2440,7 @@ out:
* called with the same type of fixture (the @data_size argument), but * called with the same type of fixture (the @data_size argument), but
* varying @test_name and @data_test arguments. * varying @test_name and @data_test arguments.
* *
* Returns: a newly allocated #GTestCase. * Returns: a newly allocated test case
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -2601,7 +2602,9 @@ g_test_fail (void)
* @format: the format string * @format: the format string
* @...: printf-like arguments to @format * @...: printf-like arguments to @format
* *
* Equivalent to [func@GLib.test_fail], but also record a message. * Indicates that a test failed and records a message.
*
* Also see [func@GLib.test_fail].
* *
* The message is formatted as if by [func@GLib.strdup_printf]. * The message is formatted as if by [func@GLib.strdup_printf].
* *
@@ -2651,8 +2654,11 @@ g_test_incomplete (const gchar *msg)
* @format: the format string * @format: the format string
* @...: printf-like arguments to @format * @...: printf-like arguments to @format
* *
* Equivalent to [func@GLib.test_incomplete], but the explanation is * Indicates that a test failed because of some incomplete
* formatted as if by [func@GLib.strdup_printf]. * functionality.
*
* Equivalent to [func@GLib.test_incomplete], but the explanation
* is formatted as if by [func@GLib.strdup_printf].
* *
* Since: 2.70 * Since: 2.70
*/ */
@@ -2697,6 +2703,8 @@ g_test_skip (const gchar *msg)
* @format: the format string * @format: the format string
* @...: printf-like arguments to @format * @...: printf-like arguments to @format
* *
* Indicates that a test was skipped.
*
* Equivalent to [func@GLib.test_skip], but the explanation * Equivalent to [func@GLib.test_skip], but the explanation
* is formatted as if by [func@GLib.strdup_printf]. * is formatted as if by [func@GLib.strdup_printf].
* *
@@ -2730,7 +2738,7 @@ g_test_skip_printf (const char *format,
* The return value of this function is only meaningful * The return value of this function is only meaningful
* if it is called from inside a test function. * if it is called from inside a test function.
* *
* Returns: `TRUE` if the test has failed * Returns: true if the test has failed
* *
* Since: 2.38 * Since: 2.38
*/ */
@@ -2743,9 +2751,11 @@ g_test_failed (void)
/** /**
* g_test_set_nonfatal_assertions: * g_test_set_nonfatal_assertions:
* *
* Changes the behaviour of the various `g_assert_*()` macros, * Changes the behaviour of the various assertion macros.
* g_test_assert_expected_messages() and the various *
* `g_test_trap_assert_*()` macros to not abort to program. * The `g_assert_*()` macros, `g_test_assert_expected_messages()`
* and the various `g_test_trap_assert_*()` macros are changed
* to not abort to program.
* *
* Instead, they will call [func@GLib.test_fail] and continue. * Instead, they will call [func@GLib.test_fail] and continue.
* (This also changes the behavior of [func@GLib.test_fail] so that * (This also changes the behavior of [func@GLib.test_fail] so that
@@ -2778,11 +2788,12 @@ g_test_set_nonfatal_assertions (void)
/** /**
* g_test_add_func: * g_test_add_func:
* @testpath: /-separated test case path name for the test. * @testpath: a /-separated name for the test
* @test_func: (scope async): The test function to invoke for this test. * @test_func: (scope async): the test function to invoke for this test
* *
* Create a new test case, similar to [func@GLib.test_create_case]. * Creates a new test case.
* *
* This function is similar to [func@GLib.test_create_case].
* However the test is assumed to use no fixture, and test suites are * However the test is assumed to use no fixture, and test suites are
* automatically created on the fly and added to the root fixture, * automatically created on the fly and added to the root fixture,
* based on the /-separated portions of @testpath. * based on the /-separated portions of @testpath.
@@ -2819,12 +2830,13 @@ g_test_add_func (const char *testpath,
/** /**
* g_test_add_data_func: * g_test_add_data_func:
* @testpath: /-separated test case path name for the test. * @testpath: a /-separated name for the test
* @test_data: Test data argument for the test function. * @test_data: data for the @test_func
* @test_func: (scope async): The test function to invoke for this test. * @test_func: (scope async): the test function to invoke for this test
* *
* Create a new test case, similar to [func@GLib.test_create_case]. * Creates a new test case.
* *
* This function is similar to [func@GLib.test_create_case].
* However the test is assumed to use no fixture, and test suites are * However the test is assumed to use no fixture, and test suites are
* automatically created on the fly and added to the root fixture, * automatically created on the fly and added to the root fixture,
* based on the /-separated portions of @testpath. The @test_data * based on the /-separated portions of @testpath. The @test_data
@@ -2854,12 +2866,12 @@ g_test_add_data_func (const char *testpath,
/** /**
* g_test_add_data_func_full: * g_test_add_data_func_full:
* @testpath: /-separated test case path name for the test. * @testpath: a /-separated name for the test
* @test_data: Test data argument for the test function. * @test_data: data for @test_func
* @test_func: The test function to invoke for this test. * @test_func: the test function to invoke for this test
* @data_free_func: #GDestroyNotify for @test_data. * @data_free_func: #GDestroyNotify for @test_data
* *
* Create a new test case, as with [func@GLib.test_add_data_func]. * Creates a new test case.
* *
* In constract to [func@GLib.test_add_data_func], this function * In constract to [func@GLib.test_add_data_func], this function
* is freeing @test_data after the test run is complete. * is freeing @test_data after the test run is complete.
@@ -2920,9 +2932,9 @@ g_test_suite_case_exists (GTestSuite *suite,
* g_test_create_suite: * g_test_create_suite:
* @suite_name: a name for the suite * @suite_name: a name for the suite
* *
* Create a new test suite with the name @suite_name. * Creates a new test suite with the name @suite_name.
* *
* Returns: A newly allocated [struct@GLib.TestSuite] instance. * Returns: a newly allocated test suite
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -2940,8 +2952,8 @@ g_test_create_suite (const char *suite_name)
/** /**
* g_test_suite_add: * g_test_suite_add:
* @suite: a `GTestSuite` * @suite: a test suite
* @test_case: a `GTestCase` * @test_case: a test case
* *
* Adds @test_case to @suite. * Adds @test_case to @suite.
* *
@@ -2959,8 +2971,8 @@ g_test_suite_add (GTestSuite *suite,
/** /**
* g_test_suite_add_suite: * g_test_suite_add_suite:
* @suite: a `GTestSuite` * @suite: a test suite
* @nestedsuite: another `GTestSuite` * @nestedsuite: another test suite
* *
* Adds @nestedsuite to @suite. * Adds @nestedsuite to @suite.
* *
@@ -2978,9 +2990,9 @@ g_test_suite_add_suite (GTestSuite *suite,
/** /**
* g_test_queue_free: * g_test_queue_free:
* @gfree_pointer: the pointer to be stored. * @gfree_pointer: the pointer to be stored
* *
* Enqueue a pointer to be released with [func@GLib.free] * Enqueues a pointer to be released with [func@GLib.free]
* during the next teardown phase. * during the next teardown phase.
* *
* This is equivalent to calling [func@GLib.test_queue_destroy] * This is equivalent to calling [func@GLib.test_queue_destroy]
@@ -2997,8 +3009,8 @@ g_test_queue_free (gpointer gfree_pointer)
/** /**
* g_test_queue_destroy: * g_test_queue_destroy:
* @destroy_func: Destroy callback for teardown phase. * @destroy_func: destroy callback for teardown phase
* @destroy_data: Destroy callback data. * @destroy_data: destroy callback data
* *
* Enqueues a callback @destroy_func to be executed during the next test case * Enqueues a callback @destroy_func to be executed during the next test case
* teardown phase. * teardown phase.
@@ -3257,9 +3269,9 @@ g_test_suite_count (GTestSuite *suite)
/** /**
* g_test_run_suite: * g_test_run_suite:
* @suite: a `GTestSuite` * @suite: a test suite
* *
* Execute the tests within @suite and all nested test suites. * Executes the tests within @suite and all nested test suites.
* *
* The test suites to be executed are filtered according to * The test suites to be executed are filtered according to
* test path arguments (`-p testpath` and `-s testpath`) as parsed by * test path arguments (`-p testpath` and `-s testpath`) as parsed by
@@ -3304,7 +3316,7 @@ g_test_run_suite (GTestSuite *suite)
/** /**
* g_test_case_free: * g_test_case_free:
* @test_case: a `GTestCase` * @test_case: a test case
* *
* Free the @test_case. * Free the @test_case.
* *
@@ -3326,9 +3338,9 @@ g_test_case_free (GTestCase *test_case)
/** /**
* g_test_suite_free: * g_test_suite_free:
* @suite: a #GTestSuite * @suite: a test suite
* *
* Free the @suite and all nested #GTestSuites. * Frees the @suite and all nested suites.
* *
* Since: 2.70 * Since: 2.70
*/ */
@@ -3632,16 +3644,16 @@ g_assertion_message_error (const char *domain,
/** /**
* g_strcmp0: * g_strcmp0:
* @str1: (nullable): a C string or `NULL` * @str1: (nullable): a string
* @str2: (nullable): another C string or `NULL` * @str2: (nullable): another string
* *
* Compares @str1 and @str2 like strcmp(). * Compares @str1 and @str2 like `strcmp()`.
* *
* Handles `NULL` gracefully by sorting it before non-`NULL` strings. * Handles `NULL` gracefully by sorting it before non-`NULL` strings.
* Comparing two `NULL` pointers returns 0. * Comparing two `NULL` pointers returns 0.
* *
* Returns: an integer less than, equal to, or greater than zero, * Returns: an integer less than, equal to, or greater than zero,
* if @str1 is <, == or > than @str2. * if @str1 is <, == or > than @str2
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -3868,10 +3880,10 @@ wait_for_child (GPid pid,
/** /**
* g_test_trap_fork: * g_test_trap_fork:
* @usec_timeout: Timeout for the forked test in micro seconds. * @usec_timeout: timeout for the forked test in microseconds
* @test_trap_flags: Flags to modify forking behaviour. * @test_trap_flags: flags to modify forking behaviour
* *
* Fork the current test program to execute a test case that might * Forks the current test program to execute a test case that might
* not return or that might abort. * not return or that might abort.
* *
* If @usec_timeout is non-0, the forked test case is aborted and * If @usec_timeout is non-0, the forked test case is aborted and
@@ -3901,7 +3913,7 @@ wait_for_child (GPid pid,
* } * }
* ]| * ]|
* *
* Returns: `TRUE` for the forked child and `FALSE` for the executing parent process. * Returns: true for the forked child and false for the executing parent process.
* *
* Since: 2.16 * Since: 2.16
* *
@@ -3984,9 +3996,9 @@ G_GNUC_END_IGNORE_DEPRECATIONS
/** /**
* g_test_trap_subprocess: * g_test_trap_subprocess:
* @test_path: (nullable): Test to run in a subprocess * @test_path: (nullable): test to run in a subprocess
* @usec_timeout: Timeout for the subprocess test in micro seconds. * @usec_timeout: timeout for the subprocess test in microseconds.
* @test_flags: Flags to modify subprocess behaviour. * @test_flags: flags to modify subprocess behaviour
* *
* Respawns the test program to run only @test_path in a subprocess. * Respawns the test program to run only @test_path in a subprocess.
* *
@@ -4006,15 +4018,14 @@ g_test_trap_subprocess (const char *test_path,
/** /**
* g_test_trap_subprocess_with_envp: * g_test_trap_subprocess_with_envp:
* @test_path: (nullable): Test to run in a subprocess * @test_path: (nullable): test to run in a subprocess
* @envp: (array zero-terminated=1) (nullable) (element-type filename): Environment * @envp: (array zero-terminated=1) (nullable) (element-type filename): environment
* to run the test in, or `NULL` to inherit the parent’s environment. This must * to run the test in
* be in the GLib filename encoding. * @usec_timeout: timeout for the subprocess test in microseconds
* @usec_timeout: Timeout for the subprocess test in micro seconds. * @test_flags: flags to modify subprocess behaviour
* @test_flags: Flags to modify subprocess behaviour.
* *
* Respawns the test program to run only @test_path in a subprocess with * Respawns the test program to run only @test_path in a subprocess with
* the given @envp environment. * a given environment.
* *
* This can be used for a test case that might not return, or that * This can be used for a test case that might not return, or that
* might abort. * might abort.
@@ -4187,11 +4198,9 @@ g_test_trap_subprocess_with_envp (const char *test_path,
/** /**
* g_test_subprocess: * g_test_subprocess:
* *
* Returns `TRUE` (after [func@GLib.test_init] has been called) * Returns true if the test program is running under [func@GLib.test_trap_subprocess].
* if the test program is running under [func@GLib.test_trap_subprocess].
* *
* Returns: `TRUE` if the test program is running under * Returns: true if the test program is running under [func@GLib.test_trap_subprocess]
* [func@GLib.test_trap_subprocess].
* *
* Since: 2.38 * Since: 2.38
*/ */
@@ -4204,9 +4213,9 @@ g_test_subprocess (void)
/** /**
* g_test_trap_has_passed: * g_test_trap_has_passed:
* *
* Check the result of the last [func@GLib.test_trap_subprocess] call. * Checks the result of the last [func@GLib.test_trap_subprocess] call.
* *
* Returns: `TRUE` if the last test subprocess terminated successfully. * Returns: true if the last test subprocess terminated successfully
* *
* Since: 2.16 * Since: 2.16
*/ */
@@ -4224,9 +4233,9 @@ g_test_trap_has_passed (void)
/** /**
* g_test_trap_reached_timeout: * g_test_trap_reached_timeout:
* *
* Check the result of the last [func@GLib.test_trap_subprocess] call. * Checks the result of the last [func@GLib.test_trap_subprocess] call.
* *
* Returns: `TRUE` if the last test subprocess got killed due to a timeout. * Returns: true if the last test subprocess got killed due to a timeout
* *
* Since: 2.16 * Since: 2.16
*/ */

28
glib/gtestutils.h
View File

@@ -439,20 +439,24 @@ void g_test_disable_crash_reporting (void);
/** /**
* g_test_add: * g_test_add:
* @testpath: The test path for a new test case. * @testpath: the test path for a new test case
* @Fixture: The type of a fixture data structure. * @Fixture: the type of a fixture data structure
* @tdata: Data argument for the test functions. * @tdata: data argument for the test functions
* @fsetup: The function to set up the fixture data. * @fsetup: the function to set up the fixture data
* @ftest: The actual test function. * @ftest: the actual test function
* @fteardown: The function to tear down the fixture data. * @fteardown: the function to tear down the fixture data
* *
* Hook up a new test case at @testpath, similar to g_test_add_func(). * Hooks up a new test case at @testpath.
* A fixture data structure with setup and teardown functions may be provided,
* similar to g_test_create_case().
* *
* g_test_add() is implemented as a macro, so that the fsetup(), ftest() and * This function is similar to [func@GLib.test_add_func].
* fteardown() callbacks can expect a @Fixture pointer as their first argument *
* in a type safe manner. They otherwise have type #GTestFixtureFunc. * A fixture data structure with setup and teardown functions
* may be provided, similar to [func@GLib.test_create_case].
*
* `g_test_add()` is implemented as a macro, so that the @fsetup,
* @ftest and @fteardown callbacks can expect a @Fixture pointer
* as their first argument in a type safe manner. They otherwise
* have type `GTestFixtureFunc`.
* *
* Since: 2.16 * Since: 2.16
*/ */