[glib] Reword some docs comments to avoid 'Returns ...'

[Ryan Lortie <ryanl src gnome org>]

commit 4f36eb0f6d1eed7b720a53114e60c8d334782fab
Author: Ryan Lortie <desrt desrt ca>
Date:   Fri Jul 22 12:57:59 2011 +0200

    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.
  *
  * <example>
  * <title>Checking the version of the GLib library</title>
@@ -463,6 +462,11 @@ const gchar * glib_check_version (guint required_major,
  *     g_error ("GLib version 1.2.0 or above is needed");
  * </programlisting>
  * </example>
+ *
+ * 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) || \