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.

diff --git a/glib/gmessages.h b/glib/gmessages.h
index 586341995125166cf1c2b96160c2907f550fa6a3..c5220e355711223bf2d185b62c06267beead24ee 100644 (file)
--- 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 a082903c0438a6456ae74050ac0415a353d3c747..a0f3cf6463b179b9aa1ee16052f8287918c166fe 100644 (file)
--- 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) || \