[geary/wip/768422-namespace-support: 4/6] Engine and IMAP stack documentation comment updates.

[Michael Gratton <mjog src gnome org>]

commit cf724f8c3ecc6f0773ab6fc781d168f2988f2e9e
Author: Michael James Gratton <mike vee net>
Date:   Thu Nov 2 16:45:02 2017 +1100

    Engine and IMAP stack documentation comment updates.

 src/engine/api/geary-account.vala                  |    2 +-
 src/engine/imap/api/imap-account.vala              |   24 ++++++++++---------
 src/engine/imap/api/imap-folder.vala               |    9 +++++++
 src/engine/imap/transport/imap-client-session.vala |   20 +++++++++++++++-
 4 files changed, 42 insertions(+), 13 deletions(-)
---
diff --git a/src/engine/api/geary-account.vala b/src/engine/api/geary-account.vala
index b6f9f41..0453348 100644
--- a/src/engine/api/geary-account.vala
+++ b/src/engine/api/geary-account.vala
@@ -84,7 +84,7 @@ public abstract class Geary.Account : BaseObject {
     public signal void folders_contents_altered(Gee.Collection<Geary.Folder> altered);
     
     /**
-     * Fired when a Folder's contents is detected having changed.
+     * Fired when a Folder's type is detected having changed.
      */
     public signal void folders_special_type(Gee.Collection<Geary.Folder> altered);
     
diff --git a/src/engine/imap/api/imap-account.vala b/src/engine/imap/api/imap-account.vala
index 14c1b0e..290af37 100644
--- a/src/engine/imap/api/imap-account.vala
+++ b/src/engine/imap/api/imap-account.vala
@@ -1,23 +1,25 @@
-/* Copyright 2016 Software Freedom Conservancy Inc.
+/*
+ * Copyright 2016 Software Freedom Conservancy Inc.
  *
  * This software is licensed under the GNU Lesser General Public License
  * (version 2.1 or later).  See the COPYING file in this distribution.
  */
 
 /**
- * Provides an interface into the IMAP stack that provides a simpler interface for a
- * Geary.Account implementation.
+ * An interface between the high-level engine API and the IMAP stack.
  *
- * Because of the complexities of the IMAP protocol, this private class takes common operations
- * that a Geary.Account implementation would need (in particular, {@link Geary.ImapEngine.Account}
- * and makes them into simple async calls.
+ * Because of the complexities of the IMAP protocol, this private
+ * class takes common operations that a Geary.Account implementation
+ * would need (in particular, {@link Geary.ImapEngine.Account} and
+ * makes them into simple async calls.
  *
- * Geary.Imap.Account manages the {@link Imap.Folder} objects it returns, but only in the sense
- * that it will not create new instances repeatedly.  Otherwise, it does not refresh or update the
- * Imap.Folders themselves (such as update their {@link Imap.StatusData} periodically).
- * That's the responsibility of the higher layers of the stack.
+ * Geary.Imap.Account manages the {@link Imap.Folder} objects it
+ * returns, but only in the sense that it will not create new
+ * instances repeatedly.  Otherwise, it does not refresh or update the
+ * Imap.Folders themselves (such as update their {@link
+ * Imap.StatusData} periodically).  That's the responsibility of the
+ * higher layers of the stack.
  */
-
 private class Geary.Imap.Account : BaseObject {
     public bool is_open { get; private set; default = false; }
     
diff --git a/src/engine/imap/api/imap-folder.vala b/src/engine/imap/api/imap-folder.vala
index f860024..3b726e7 100644
--- a/src/engine/imap/api/imap-folder.vala
+++ b/src/engine/imap/api/imap-folder.vala
@@ -9,7 +9,16 @@ private errordomain Geary.Imap.FolderError {
     RETRY
 }
 
+/**
+ * An interface between the high-level engine API and a single IMAP mailbox.
+ *
+ * When opening, this class will claim a {@link ClientSession} and
+ * issue an IMAP SELECT command for the mailbox represented by this
+ * folder. On closing, the session is released, causing it to be
+ * returned to the pool where an IMAP CLOSE will be issued.
+ */
 private class Geary.Imap.Folder : BaseObject {
+
     private const Geary.Email.Field BASIC_FETCH_FIELDS = Email.Field.ENVELOPE | Email.Field.DATE
         | Email.Field.ORIGINATORS | Email.Field.RECEIVERS | Email.Field.REFERENCES
         | Email.Field.SUBJECT | Email.Field.HEADER;
diff --git a/src/engine/imap/transport/imap-client-session.vala 
b/src/engine/imap/transport/imap-client-session.vala
index 268d512..35669a9 100644
--- a/src/engine/imap/transport/imap-client-session.vala
+++ b/src/engine/imap/transport/imap-client-session.vala
@@ -4,6 +4,24 @@
  * (version 2.1 or later).  See the COPYING file in this distribution.
  */
 
+/**
+ * High-level interface to a single IMAP server connection.
+ *
+ * The client session is responsible for opening, maintaining and
+ * closing a TCP connection to an IMAP server. When opening, the
+ * session will obtain and maintain capabilities, establish a StartTLS
+ * session if appropriate, authenticate, and obtain
+ * connection-specific information about the server such as the name
+ * used for the INBOX and any mailbox namespaces. When connecting has
+ * completed successfully, the connection will be in the IMAP
+ * authenticated state.
+ *
+ * Any IMAP commands that affect the IMAP connection's state (LOGIN,
+ * LOGOUT, SELECT, etc) must be executed by calling the appropriate
+ * method on this object. For example, call `login_async` rather than
+ * sending a {@link LoginCommand}. Other commands can be sent via
+ * {@link send_command_async} and {@link send_multiple_commands_async}.
+ */
 public class Geary.Imap.ClientSession : BaseObject {
     // 30 min keepalive required to maintain session
     public const uint MIN_KEEPALIVE_SEC = 30 * 60;
@@ -216,7 +234,7 @@ public class Geary.Imap.ClientSession : BaseObject {
     public signal void status_response_received(StatusResponse status_response);
     
     /**
-     * Fired before the specific {@link ServerData} signals (i.e. {@link capability}, {@link exists}
+     * Fired after the specific {@link ServerData} signals (i.e. {@link capability}, {@link exists}
      * {@link expunge}, etc.)
      */
     public signal void server_data_received(ServerData server_data);