[glib] gmessages: Add doc cross-refs about enabling structured logging

[Philip Withnall <pwithnall src gnome org>]

commit a079de930e9a2311ec7fb48e65db81bada3b5dfa
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Fri Aug 12 11:53:19 2016 +0200

    gmessages: Add doc cross-refs about enabling structured logging
    
    Ensure that all the old log handler documentation includes
    cross-references to a new section about how to enable structured logging
    (tl;dr: #define G_LOG_USE_STRUCTURED).
    
    https://bugzilla.gnome.org/show_bug.cgi?id=769785

 glib/gmessages.c |   82 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 files changed, 72 insertions(+), 10 deletions(-)
---
diff --git a/glib/gmessages.c b/glib/gmessages.c
index 79de68d..db6761f 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -52,11 +52,11 @@
  *
  * The convenience macros g_info(), g_message(), g_debug(), g_warning() and g_error()
  * will use the traditional g_log() API unless you define the symbol
- * `G_LOG_USE_STRUCTURED` before including `glib.h`. But note that even messages
+ * %G_LOG_USE_STRUCTURED before including `glib.h`. But note that even messages
  * logged through the traditional g_log() API are ultimatively passed to
  * g_log_structured(), so that all log messages end up in same destination.
- * If `G_LOG_USE_STRUCTURED` is defined, g_test_expect_message() will become
- * will become ineffective for the wrapper macros g_warning() and friends (see
+ * If %G_LOG_USE_STRUCTURED is defined, g_test_expect_message() will become
+ * ineffective for the wrapper macros g_warning() and friends (see
  * [Testing for Messages][testing-for-messages]).
  *
  * The support for structured logging was motivated by the following needs (some
@@ -94,6 +94,16 @@
  *  * Color output needed to be supported on the terminal, to make reading
  *    through logs easier.
  *
+ * ## Using Structured Logging
+ *
+ * To use structured logging (rather than the old-style logging), either use
+ * the g_log_structured() and g_log_structured_array() functions; or define
+ * `G_LOG_USE_STRUCTURED` before including any GLib header, and use the
+ * g_message(), g_debug(), g_error() (etc.) macros.
+ *
+ * You do not need to define `G_LOG_USE_STRUCTURED` to use g_log_structured(),
+ * but it is a good idea to avoid confusion.
+ *
  * ## Log Domains
  *
  * Log domains may be used to broadly split up the origins of log messages.
@@ -219,6 +229,9 @@
  * G_LOG_FATAL_MASK:
  *
  * GLib log levels that are considered fatal by default.
+ *
+ * This is not used if structured logging is enabled; see
+ * [Using Structured Logging][using-structured-logging].
  */
 
 /**
@@ -236,6 +249,9 @@
  * custom log handler functions behave similarly, so that logging calls in user
  * code do not need modifying to add a new-line character to the message if the
  * log handler is changed.
+ *
+ * This is not used if structured logging is enabled; see
+ * [Using Structured Logging][using-structured-logging].
  */
 
 /**
@@ -277,6 +293,10 @@
  * 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
  * manually.
+ *
+ * If structured logging is enabled, this will use g_log_structured();
+ * otherwise it will use g_log(). See
+ * [Using Structured Logging][using-structured-logging].
  */
 
 /**
@@ -297,6 +317,10 @@
  * If g_log_default_handler() is used as the log handler function,
  * a newline character will automatically be appended to @..., and
  * need not be entered manually.
+ *
+ * If structured logging is enabled, this will use g_log_structured();
+ * otherwise it will use g_log(). See
+ * [Using Structured Logging][using-structured-logging].
  */
 
 /**
@@ -318,6 +342,10 @@
  * 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
  * manually.
+ *
+ * If structured logging is enabled, this will use g_log_structured();
+ * otherwise it will use g_log(). See
+ * [Using Structured Logging][using-structured-logging].
  */
 
 /**
@@ -341,6 +369,9 @@
  * character will automatically be appended to @..., and need not be entered
  * manually.
  *
+ * If structured logging is enabled, this will use g_log_structured();
+ * otherwise it will use g_log(). See
+ * [Using Structured Logging][using-structured-logging].
  */
 
 /**
@@ -358,6 +389,10 @@
  * g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is
  * set appropriately.
  *
+ * If structured logging is enabled, this will use g_log_structured();
+ * otherwise it will use g_log(). See
+ * [Using Structured Logging][using-structured-logging].
+ *
  * Since: 2.40
  */
 
@@ -376,6 +411,10 @@
  * g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is
  * set appropriately.
  *
+ * If structured logging is enabled, this will use g_log_structured();
+ * otherwise it will use g_log(). See
+ * [Using Structured Logging][using-structured-logging].
+ *
  * Since: 2.6
  */
 
@@ -604,7 +643,7 @@ g_log_domain_get_handler_L (GLogDomain      *domain,
  * Structured log messages (using g_log_structured() and
  * g_log_structured_array()) are fatal only if the default log writer is used;
  * otherwise it is up to the writer function to determine which log messages
- * are fatal.
+ * are fatal. See [Using Structured Logging][using-structured-logging].
  *
  * Returns: the old fatal mask
  */
@@ -641,7 +680,8 @@ g_log_set_always_fatal (GLogLevelFlags fatal_mask)
  * This has no effect on structured log messages (using g_log_structured() or
  * g_log_structured_array()). To change the fatal behaviour for specific log
  * messages, programs must install a custom log writer function using
- * g_log_set_writer_func().
+ * g_log_set_writer_func(). See
+ * [Using Structured Logging][using-structured-logging].
  *
  * Returns: the old fatal mask for the log domain
  */
@@ -695,6 +735,9 @@ g_log_set_fatal_mask (const gchar   *log_domain,
  * you want to set a handler for this log level you must combine it with
  * #G_LOG_FLAG_FATAL.
  *
+ * This has no effect if structured logging is enabled; see
+ * [Using Structured Logging][using-structured-logging].
+ *
  * Here is an example for adding a log handler for all warning messages
  * in the default domain:
  * |[<!-- language="C" --> 
@@ -739,6 +782,9 @@ g_log_set_handler (const gchar       *log_domain,
  *
  * Like g_log_sets_handler(), but takes a destroy notify for the @user_data.
  *
+ * This has no effect if structured logging is enabled; see
+ * [Using Structured Logging][using-structured-logging].
+ *
  * Returns: the id of the new handler
  *
  * Since: 2.46
@@ -791,6 +837,9 @@ g_log_set_handler_full (const gchar    *log_domain,
  * and log level combination. By default, GLib uses
  * g_log_default_handler() as default log handler.
  *
+ * This has no effect if structured logging is enabled; see
+ * [Using Structured Logging][using-structured-logging].
+ *
  * Returns: the previous default log handler
  *
  * Since: 2.6
@@ -834,7 +883,8 @@ g_log_set_default_handler (GLogFunc log_func,
  * This handler also has no effect on structured log messages (using
  * g_log_structured() or g_log_structured_array()). To change the fatal
  * behaviour for specific log messages, programs must install a custom log
- * writer function using g_log_set_writer_func().
+ * writer function using g_log_set_writer_func().See
+ * [Using Structured Logging][using-structured-logging].
  *
  * Since: 2.22
  **/
@@ -855,6 +905,9 @@ g_test_log_set_fatal_handler (GTestLogFatalFunc log_func,
  *     in g_log_set_handler()
  *
  * Removes the log handler.
+ *
+ * This has no effect if structured logging is enabled; see
+ * [Using Structured Logging][using-structured-logging].
  */
 void
 g_log_remove_handler (const gchar *log_domain,
@@ -1117,6 +1170,9 @@ static GSList *expected_messages = NULL;
  * 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
  * manually.
+ *
+ * If [structured logging is enabled][using-structured-logging] this will
+ * output via the structured log writer function (see g_log_set_writer_func()).
  */
 void
 g_logv (const gchar   *log_domain,
@@ -1265,6 +1321,9 @@ g_logv (const gchar   *log_domain,
  * 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
  * manually.
+ *
+ * If [structured logging is enabled][using-structured-logging] this will
+ * output via the structured log writer function (see g_log_set_writer_func()).
  */
 void
 g_log (const gchar   *log_domain,
@@ -2582,6 +2641,9 @@ escape_string (GString *string)
  * stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL,
  * %G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for
  * the rest.
+ *
+ * This has no effect if structured logging is enabled; see
+ * [Using Structured Logging][using-structured-logging].
  */
 void
 g_log_default_handler (const gchar   *log_domain,
@@ -2681,8 +2743,8 @@ g_set_print_handler (GPrintFunc func)
  * g_print() should not be used from within libraries for debugging
  * messages, since it may be redirected by applications to special
  * purpose message windows or even files. Instead, libraries should
- * use g_log(), or the convenience functions g_message(), g_warning()
- * and g_error().
+ * use g_log(), g_log_structured(), or the convenience macros g_message(),
+ * g_warning() and g_error().
  */
 void
 g_print (const gchar *format,
@@ -2760,8 +2822,8 @@ g_set_printerr_handler (GPrintFunc func)
  * new-line character.
  *
  * g_printerr() should not be used from within libraries.
- * Instead g_log() should be used, or the convenience functions
- * g_message(), g_warning() and g_error().
+ * Instead g_log() or g_log_structured() should be used, or the convenience
+ * macros g_message(), g_warning() and g_error().
  */
 void
 g_printerr (const gchar *format,