[glib] gmessages: Update advice for G_LOG_DOMAIN

[Philip Withnall <pwithnall src gnome org>]

commit 493723b4d92c60037c5fa46a049b374925a60d88
Author: Philip Withnall <philip tecnocode co uk>
Date:   Mon Jan 30 22:50:00 2017 +0000

    gmessages: Update advice for G_LOG_DOMAIN
    
    Suggest defining it for all code — for applications as well as for
    libraries. This allows G_MESSAGES_DEBUG=my-app to be used to filter out
    all messages from libraries which it uses, for example.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=777956

 glib/gmessages.c |   14 +++++++++++---
 1 files changed, 11 insertions(+), 3 deletions(-)
---
diff --git a/glib/gmessages.c b/glib/gmessages.c
index d97da90..4b9e836 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -273,19 +273,27 @@ myInvalidParameterHandler(const wchar_t *expression,
 /**
  * G_LOG_DOMAIN:
  *
- * Defines the log domain.
+ * Defines the log domain. See [Log Domains](#log-domains).
  *
  * Libraries should define this so that any messages
  * which they log can be differentiated from messages from other
  * libraries and application code. But be careful not to define
  * it in any public header files.
  *
- * For example, GTK+ uses this in its Makefile.am:
+ * Log domains must be unique, and it is recommended that they are the
+ * application or library name, optionally followed by a hyphen and a sub-domain
+ * name. For example, `bloatpad` or `bloatpad-io`.
+ *
+ * If undefined, it defaults to the default %NULL (or `""`) log domain; this is
+ * not advisable, as it cannot be filtered against using the `G_MESSAGES_DEBUG`
+ * environment variable.
+ *
+ * For example, GTK+ uses this in its `Makefile.am`:
  * |[
  * AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\"
  * ]|
  *
- * Applications can choose to leave it as the default %NULL (or "")
+ * Applications can choose to leave it as the default %NULL (or `""`)
  * domain. However, defining the domain offers the same advantages as
  * above.
  *