[glib: 1/2] gmessages: Clarify documentation about aborting on fatal log levels

[Emmanuele Bassi <ebassi src gnome org>]

commit a0456f9c96e8b31e352f124f5f7bdd9dfb3c8b8e
Author: Philip Withnall <withnall endlessm com>
Date:   Mon Aug 20 23:41:53 2018 +0100

    gmessages: Clarify documentation about aborting on fatal log levels
    
    Clarify that we actually raise SIGTRAP rather than calling abort(). We
    haven’t called abort() since about 2011, when commit
    a04efe6afb63d54e12ff8f329cbaf458a2e31b26 changed the logic to use
    SIGTRAP to make it possible to skip past fatal log messages in the
    debugger if they weren’t relevant to the problem being debugged.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    https://gitlab.gnome.org/GNOME/glib/issues/1448

 glib/gbacktrace.h |  5 ++++-
 glib/gmessages.c  | 18 ++++++++++--------
 2 files changed, 14 insertions(+), 9 deletions(-)
---
diff --git a/glib/gbacktrace.h b/glib/gbacktrace.h
index d7322f4e2..9e9cba151 100644
--- a/glib/gbacktrace.h
+++ b/glib/gbacktrace.h
@@ -47,8 +47,11 @@ void g_on_error_stack_trace (const gchar *prg_name);
  *
  * Inserts a breakpoint instruction into the code.
  *
- * On x86 and alpha systems this is implemented as a soft interrupt
+ * On architectures which support it, this is implemented as a soft interrupt
  * and on other architectures it raises a `SIGTRAP` signal.
+ *
+ * `SIGTRAP` is used rather than abort() to allow breakpoints to be skipped past
+ * in a debugger if they are not the desired target of debugging.
  */
 #if (defined (__i386__) || defined (__x86_64__)) && defined (__GNUC__) && __GNUC__ >= 2
 #  define G_BREAKPOINT()        G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END
diff --git a/glib/gmessages.c b/glib/gmessages.c
index b468ef3b7..569fe2cf8 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -428,8 +428,8 @@ myInvalidParameterHandler(const wchar_t *expression,
  * preferred for that instead, as it allows calling functions to perform actions
  * conditional on the type of error.
  *
- * Error messages are always fatal, resulting in a call to
- * abort() to terminate the application. This function will
+ * Error messages are always fatal, resulting in a call to G_BREAKPOINT()
+ * to terminate the application. This function will
  * result in a core dump; don't use it for errors you expect.
  * Using this function indicates a bug in your program, i.e.
  * an assertion failure.
@@ -1238,8 +1238,9 @@ static GSList *expected_messages = NULL;
  *
  * Logs an error or debugging message.
  *
- * If the log level has been set as fatal, the abort()
- * function is called to terminate the program.
+ * If the log level has been set as fatal, G_BREAKPOINT() is called
+ * to terminate the program. See the documentation for G_BREAKPOINT() for
+ * details of the debugging options this provides.
  *
  * If g_log_default_handler() is used as the log handler function, a new-line
  * character will automatically be appended to @..., and need not be entered
@@ -1389,8 +1390,9 @@ g_logv (const gchar   *log_domain,
  *
  * Logs an error or debugging message.
  *
- * If the log level has been set as fatal, the abort()
- * function is called to terminate the program.
+ * If the log level has been set as fatal, G_BREAKPOINT() is called
+ * to terminate the program. See the documentation for G_BREAKPOINT() for
+ * details of the debugging options this provides.
  *
  * If g_log_default_handler() is used as the log handler function, a new-line
  * character will automatically be appended to @..., and need not be entered
@@ -1571,7 +1573,7 @@ done_query:
  * Log a message with structured data. The message will be passed through to
  * the log writer set by the application using g_log_set_writer_func(). If the
  * message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will
- * be aborted at the end of this function. If the log writer returns
+ * be aborted by calling G_BREAKPOINT() at the end of this function. If the log writer returns
  * %G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried.
  * See the documentation for #GLogWriterFunc for information on chaining
  * writers.
@@ -3040,7 +3042,7 @@ escape_string (GString *string)
  * allows to install an alternate default log handler.
  * This is used if no log handler has been set for the particular log
  * domain and log level combination. It outputs the message to stderr
- * or stdout and if the log level is fatal it calls abort(). It automatically
+ * or stdout and if the log level is fatal it calls G_BREAKPOINT(). It automatically
  * prints a new-line character after the message, so one does not need to be
  * manually included in @message.
  *