From 5ce6517b3b27f2ee39bef0be5d4c0c4bfaefd891 Mon Sep 17 00:00:00 2001
From: Michael Gratton <mike@vee.net>
Date: Fri, 17 Apr 2020 08:52:42 +1000
Subject: [PATCH] Geary.Logging: Add/update API docs for the package and a few
 functions

---
 .../application/application-client.vala       |  4 +--
 src/engine/util/util-logging.vala             | 25 ++++++++++++++++---
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/src/client/application/application-client.vala b/src/client/application/application-client.vala
index 523a680f..50516548 100644
--- a/src/client/application/application-client.vala
+++ b/src/client/application/application-client.vala
@@ -112,7 +112,7 @@ public class Application.Client : Gtk.Application {
           N_("Log folder normalization"), null },
         { OPTION_LOG_IMAP, 0, 0, GLib.OptionArg.NONE, null,
           /// Command line option
-          N_("Log IMAP messages"), null },
+          N_("Log IMAP network activity"), null },
         { OPTION_LOG_REPLAY_QUEUE, 0, 0, GLib.OptionArg.NONE, null,
           /// Command line option. The IMAP replay queue is how changes
           /// on the server are replicated on the client.  It could
@@ -120,7 +120,7 @@ public class Application.Client : Gtk.Application {
           N_("Log IMAP replay queue"), null },
         { OPTION_LOG_SMTP, 0, 0, GLib.OptionArg.NONE, null,
           /// Command line option
-          N_("Log SMTP messages"), null },
+          N_("Log SMTP network activity"), null },
         { OPTION_LOG_SQL, 0, 0, GLib.OptionArg.NONE, null,
           /// Command line option
           N_("Log database queries (generates lots of messages)"), null },
diff --git a/src/engine/util/util-logging.vala b/src/engine/util/util-logging.vala
index 5294355b..c4c517cd 100644
--- a/src/engine/util/util-logging.vala
+++ b/src/engine/util/util-logging.vala
@@ -7,6 +7,24 @@
  */
 
 
+/**
+ * Logging infrastructure for the applications and the engine.
+ *
+ * Applications using the engine may register {@link
+ * default_log_writer} as the GLib structured logging writer. Doing so
+ * enables the creation of a {@link Record} class for each log message
+ * received, control over which logging messages are displayed, and
+ * enabling applications to display logging information and include it
+ * in bug reports.
+ *
+ * The engine's logging infrastructure is built with and assumes GLib
+ * structured logging is enabled.
+ *
+ * Engine classes that perform important context-specific debug
+ * logging (i.e in the context of a specific account or folder),
+ * should implement the {@link Source} interface so they can provide
+ * logging context and a custom logging sub-domain (if needed).
+ */
 namespace Geary.Logging {
 
 
@@ -189,7 +207,7 @@ namespace Geary.Logging {
 
 
     /**
-     * A GLib structured logging to record structured logging calls.
+     * A GLib structured logging writer that records logging messages.
      *
      * Installing this function as the GLib structured log writer by
      * passing it in a call to {@link GLib.Log.set_writer_func} will
@@ -200,9 +218,8 @@ namespace Geary.Logging {
      * via {@link get_earliest_record}, {@link get_latest_record}, and
      * {@link set_log_listener}.
      *
-     * Further if a destination stream has been set via a call to
-     * {@link log_to}, then DEBUG-level, INFORMATION-level, and
-     * MESSAGE-level structured log messages will be printed to the
+     * Further, if a destination stream has been set via a call to
+     * {@link log_to}, structured log messages will be printed to the
      * given stream.
      */
     public GLib.LogWriterOutput default_log_writer(GLib.LogLevelFlags levels,