[glib] gmessages: Expand documentation on GLogWriterFunc chaining

[Philip Withnall <pwithnall src gnome org>]

commit ac0b0c84f7d310012d6960d96bb5daa62b8d2d48
Author: Philip Withnall <withnall endlessm com>
Date:   Wed Jun 14 09:56:13 2017 +0100

    gmessages: Expand documentation on GLogWriterFunc chaining
    
    As prompted by Marc-Andre Lureau.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    https://bugzilla.gnome.org/show_bug.cgi?id=661926

 glib/gmessages.c |    5 ++++-
 glib/gmessages.h |    7 +++++++
 2 files changed, 11 insertions(+), 1 deletions(-)
---
diff --git a/glib/gmessages.c b/glib/gmessages.c
index 60081c4..cac882f 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -1586,7 +1586,10 @@ 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.
+ * be aborted 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.
  *
  * The structured data is provided as key–value pairs, where keys are UTF-8
  * strings, and values are arbitrary pointers — typically pointing to UTF-8
diff --git a/glib/gmessages.h b/glib/gmessages.h
index 3c0b0d9..ee0dca8 100644
--- a/glib/gmessages.h
+++ b/glib/gmessages.h
@@ -179,6 +179,13 @@ struct _GLogField
  * but is provided separately for convenience of deciding whether or where to
  * output the log entry.
  *
+ * Writer functions should return %G_LOG_WRITER_HANDLED if they handled the log
+ * message successfully or if they deliberately ignored it. If there was an
+ * error handling the message (for example, if the writer function is meant to
+ * send messages to a remote logging server and there is a network error), it
+ * should return %G_LOG_WRITER_UNHANDLED. This allows writer functions to be
+ * chained and fall back to simpler handlers in case of failure.
+ *
  * Returns: %G_LOG_WRITER_HANDLED if the log entry was handled successfully;
  *    %G_LOG_WRITER_UNHANDLED otherwise
  * Since: 2.50