[glib] gmessages: Give examples of G_DEBUG with gdb in the documentation

[Philip Withnall <pwithnall src gnome org>]

commit 63e9d109fd3705067ef3b6a73062965856802bde
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Nov 10 10:26:01 2017 +0000

    gmessages: Give examples of G_DEBUG with gdb in the documentation
    
    Some of the documentation linked to information about G_DEBUG already,
    but most of it didn’t, and there were no examples. People need obvious
    examples.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    https://bugzilla.gnome.org/show_bug.cgi?id=790157

 glib/gmessages.c |   18 ++++++++++++++++--
 glib/gmessages.h |   17 +++++++++++++++++
 2 files changed, 33 insertions(+), 2 deletions(-)
---
diff --git a/glib/gmessages.c b/glib/gmessages.c
index ceb4275..8c9f558 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -389,7 +389,14 @@ myInvalidParameterHandler(const wchar_t *expression,
  *
  * You can make warnings fatal at runtime by setting the `G_DEBUG`
  * environment variable (see
- * [Running GLib Applications](glib-running.html)).
+ * [Running GLib Applications](glib-running.html)):
+ *
+ * |[
+ *   G_DEBUG=fatal-warnings gdb ./my-program
+ * ]|
+ *
+ * Any unrelated failures can be skipped over in
+ * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
  *
  * If g_log_default_handler() is used as the log handler function,
  * a newline character will automatically be appended to @..., and
@@ -414,7 +421,14 @@ myInvalidParameterHandler(const wchar_t *expression,
  *
  * You can also make critical warnings fatal at runtime by
  * setting the `G_DEBUG` environment variable (see
- * [Running GLib Applications](glib-running.html)).
+ * [Running GLib Applications](glib-running.html)):
+ *
+ * |[
+ *   G_DEBUG=fatal-warnings gdb ./my-program
+ * ]|
+ *
+ * Any unrelated failures can be skipped over in
+ * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
  *
  * The message should typically *not* be translated to the
  * user's language.
diff --git a/glib/gmessages.h b/glib/gmessages.h
index 53a27dd..1815186 100644
--- a/glib/gmessages.h
+++ b/glib/gmessages.h
@@ -535,6 +535,17 @@ GPrintFunc      g_set_printerr_handler  (GPrintFunc      func);
  *
  * If `G_DISABLE_CHECKS` is defined then the check is not performed.  You
  * should therefore not depend on any side effects of @expr.
+ *
+ * To debug failure of a g_return_if_fail() check, run the code under a debugger
+ * with `G_DEBUG=fatal-criticals` or `G_DEBUG=fatal-warnings` defined in the
+ * environment (see [Running GLib Applications](glib-running.html)):
+ *
+ * |[
+ *   G_DEBUG=fatal-warnings gdb ./my-program
+ * ]|
+ *
+ * Any unrelated failures can be skipped over in
+ * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
  */
 #define g_return_if_fail(expr) G_STMT_START{ (void)0; }G_STMT_END
 
@@ -559,6 +570,8 @@ GPrintFunc      g_set_printerr_handler  (GPrintFunc      func);
  *
  * If `G_DISABLE_CHECKS` is defined then the check is not performed.  You
  * should therefore not depend on any side effects of @expr.
+ *
+ * See g_return_if_fail() for guidance on how to debug failure of this check.
  */
 #define g_return_val_if_fail(expr,val) G_STMT_START{ (void)0; }G_STMT_END
 
@@ -567,6 +580,8 @@ GPrintFunc      g_set_printerr_handler  (GPrintFunc      func);
  *
  * Logs a critical message and returns from the current function.
  * This can only be used in functions which do not return a value.
+ *
+ * See g_return_if_fail() for guidance on how to debug failure of this check.
  */
 #define g_return_if_reached() G_STMT_START{ return; }G_STMT_END
 
@@ -575,6 +590,8 @@ GPrintFunc      g_set_printerr_handler  (GPrintFunc      func);
  * @val: the value to return from the current function
  *
  * Logs a critical message and returns @val.
+ *
+ * See g_return_if_fail() for guidance on how to debug failure of this check.
  */
 #define g_return_val_if_reached(val) G_STMT_START{ return (val); }G_STMT_END