From 4f36eb0f6d1eed7b720a53114e60c8d334782fab Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Fri, 22 Jul 2011 12:57:59 +0200 Subject: [PATCH] Reword some docs comments to avoid 'Returns ...' If gtk-doc sees 'Returns ...' written in the text of the documentation for a macro, it thinks that you are talking about the return value. Avoid doing that and use 'Returns:' explicitly if we mean to. --- glib/gmessages.h | 21 +++++++++++++-------- glib/gutils.h | 10 +++++++--- 2 files changed, 20 insertions(+), 11 deletions(-) diff --git a/glib/gmessages.h b/glib/gmessages.h index 5863419..c5220e3 100644 --- a/glib/gmessages.h +++ b/glib/gmessages.h @@ -273,11 +273,13 @@ GPrintFunc g_set_printerr_handler (GPrintFunc func); * g_return_if_fail: * @expr: the expression to check * - * Returns from the current function if the expression - * is not true. If the expression evaluates to %FALSE, - * a critical message is logged and the function returns. - * This can only be used in functions which do not return - * a value. + * Verifies that the expression evaluates to %TRUE. If the expression + * evaluates to %FALSE, a critical message is logged and the current + * function returns. This can only be used in functions which do not + * return a value. + * + * If G_DISABLE_CHECKS is defined then the check is not performed. You + * should therefore not depend on any side effects of @expr. */ #define g_return_if_fail(expr) G_STMT_START{ (void)0; }G_STMT_END @@ -287,9 +289,12 @@ GPrintFunc g_set_printerr_handler (GPrintFunc func); * @val: the value to return from the current function * if the expression is not true * - * Returns from the current function, returning the value @val, - * if the expression is not true. If the expression evaluates - * to %FALSE, a critical message is logged and @val is returned. + * Verifies that the expression evaluates to %TRUE. If the expression + * evaluates to %FALSE, a critical message is logged and @val is + * returned from the current function. + * + * If G_DISABLE_CHECKS is defined then the check is not performed. You + * should therefore not depend on any side effects of @expr. */ #define g_return_val_if_fail(expr,val) G_STMT_START{ (void)0; }G_STMT_END diff --git a/glib/gutils.h b/glib/gutils.h index a082903..a0f3cf6 100644 --- a/glib/gutils.h +++ b/glib/gutils.h @@ -452,9 +452,8 @@ const gchar * glib_check_version (guint required_major, * @minor: the minor version to check for * @micro: the micro version to check for * - * Checks the version of the GLib library. - * Returns %TRUE if the version of the GLib header files - * is the same as or newer than the passed-in version. + * Checks the version of the GLib library that is being compiled + * against. * * * Checking the version of the GLib library @@ -463,6 +462,11 @@ const gchar * glib_check_version (guint required_major, * g_error ("GLib version 1.2.0 or above is needed"); * * + * + * See glib_check_version() for a runtime check. + * + * Returns: %TRUE if the version of the GLib header files + * is the same as or newer than the passed-in version. */ #define GLIB_CHECK_VERSION(major,minor,micro) \ (GLIB_MAJOR_VERSION > (major) || \ -- 2.7.4