From 1ea340529737a0a020ac67353e24661eaf3678b1 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 17 Aug 2013 15:23:41 -0400 Subject: [PATCH] Update the documentation for assertion macros The assertion macros that are part of gtestutils (but not g_assert) can now be made non-fatal. Update the documentation to reflect that. https://bugzilla.gnome.org/show_bug.cgi?id=692125 --- glib/gtestutils.c | 56 +++++++++++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 21 deletions(-) diff --git a/glib/gtestutils.c b/glib/gtestutils.c index 3aec27e6e..353a2db2e 100644 --- a/glib/gtestutils.c +++ b/glib/gtestutils.c @@ -354,6 +354,12 @@ * * Debugging macro to check that an expression is true. * + * If the assertion fails (i.e. the expression is not true), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * * Since: 2.38 */ @@ -363,6 +369,12 @@ * * Debugging macro to check an expression is false. * + * If the assertion fails (i.e. the expression is not false), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * * Since: 2.38 */ @@ -372,6 +384,12 @@ * * Debugging macro to check an expression is %NULL. * + * If the assertion fails (i.e. the expression is not %NULL), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * * Since: 2.38 */ @@ -382,12 +400,13 @@ * One of ==, !=, <, >, <=, >=. * @s2: another string (may be %NULL) * - * Debugging macro to terminate the application with a warning - * message if a string comparison fails. The strings are compared - * using g_strcmp0(). + * Debugging macro to compare two strings. If the comparison fails, + * an error message is logged and the application is either terminated + * or the testcase marked as failed. + * The strings are compared using g_strcmp0(). * * The effect of g_assert_cmpstr (s1, op, s2) is - * the same as g_assert (g_strcmp0 (s1, s2) op 0). + * the same as g_assert_true (g_strcmp0 (s1, s2) op 0). * The advantage of this macro is that it can produce a message that * includes the actual values of @s1 and @s2. * @@ -405,11 +424,10 @@ * One of ==, !=, <, >, <=, >=. * @n2: another integer * - * Debugging macro to terminate the application with a warning - * message if an integer comparison fails. + * Debugging macro to compare two integers. * * The effect of g_assert_cmpint (n1, op, n2) is - * the same as g_assert (n1 op n2). The advantage + * the same as g_assert_true (n1 op n2). The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * @@ -423,11 +441,10 @@ * One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * - * Debugging macro to terminate the application with a warning - * message if an unsigned integer comparison fails. + * Debugging macro to compare two unsigned integers. * * The effect of g_assert_cmpuint (n1, op, n2) is - * the same as g_assert (n1 op n2). The advantage + * the same as g_assert_true (n1 op n2). The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * @@ -441,8 +458,7 @@ * One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * - * Debugging macro to terminate the application with a warning - * message if an unsigned integer comparison fails. + * Debugging macro to compare to unsigned integers. * * This is a variant of g_assert_cmpuint() that displays the numbers * in hexadecimal notation in the message. @@ -457,11 +473,10 @@ * One of ==, !=, <, >, <=, >=. * @n2: another floating point number * - * Debugging macro to terminate the application with a warning - * message if a floating point number comparison fails. + * Debugging macro to compare two floating point numbers. * * The effect of g_assert_cmpfloat (n1, op, n2) is - * the same as g_assert (n1 op n2). The advantage + * the same as g_assert_true (n1 op n2). The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * @@ -472,11 +487,10 @@ * g_assert_no_error: * @err: a #GError, possibly %NULL * - * Debugging macro to terminate the application with a warning - * message if a method has returned a #GError. + * Debugging macro to check that a #GError is not set. * * The effect of g_assert_no_error (err) is - * the same as g_assert (err == NULL). The advantage + * the same as g_assert_true (err == NULL). The advantage * of this macro is that it can produce a message that includes * the error message and code. * @@ -489,11 +503,11 @@ * @dom: the expected error domain (a #GQuark) * @c: the expected error code * - * Debugging macro to terminate the application with a warning - * message if a method has not returned the correct #GError. + * Debugging macro to check that a method has returned + * the correct #GError. * * The effect of g_assert_error (err, dom, c) is - * the same as g_assert (err != NULL && err->domain + * the same as g_assert_true (err != NULL && err->domain * == dom && err->code == c). The advantage of this * macro is that it can produce a message that includes the incorrect * error message and code.