GNOME.org
 

[geary/wip/789924-network-transition-redux: 58/64] Improve doc comments for Email, Folder and RFC822.Message.

commit e78313df52e2913094f67a16a2cdad0e575e57a7
Author: Michael James Gratton <mike vee net>
Date:   Mon Feb 26 23:36:22 2018 +1100

    Improve doc comments for Email, Folder and RFC822.Message.
    
    fixup and reword 79b9bbe

 src/engine/api/geary-email.vala       |  128 ++++++++++++++----
 src/engine/api/geary-folder.vala      |  237 ++++++++++++++++++++------------
 src/engine/rfc822/rfc822-message.vala |    8 +
 3 files changed, 258 insertions(+), 115 deletions(-)
---
diff --git a/src/engine/api/geary-email.vala b/src/engine/api/geary-email.vala
index e9cc1cd..1240150 100644
--- a/src/engine/api/geary-email.vala
+++ b/src/engine/api/geary-email.vala
@@ -1,14 +1,30 @@
-/* Copyright 2016 Software Freedom Conservancy Inc.
+/*
+ * Copyright 2016 Software Freedom Conservancy Inc.
+ * Copyright 2018 Michael Gratton <mike vee net>
  *
  * This software is licensed under the GNU Lesser General Public License
  * (version 2.1 or later).  See the COPYING file in this distribution.
  */
 
 /**
- * Representation of a single email message in the engine.
+ * An Email represents a single RFC 822 style email message.
  *
- * This class encapsulates an email, attachments and its related
- * server and database state.
+ * This class provides a common abstraction over different
+ * representations of email messages, allowing messages from different
+ * mail systems, from both local and remote sources, and locally
+ * composed email messages to all be represented by a single
+ * object. While this object represents a RFC 822 message, it also
+ * holds additional metadata about an email not specified by that
+ * format, such as its unique {@link id}, and unread state and other
+ * {@link email_flags}.
+ *
+ * Email objects may by constructed in many ways, but are usually
+ * obtained via a {@link Folder}. Email objects may be partial
+ * representations of messages, in cases where a remote message has
+ * not been fully downloaded, or a local message not fully loaded from
+ * a database. This can be checked via an email's {@link fields}
+ * property, and if the currently loaded fields are not sufficient,
+ * then additional fields can be loaded via a folder.
  */
 public class Geary.Email : BaseObject {
 
@@ -18,35 +34,75 @@ public class Geary.Email : BaseObject {
     public const int MAX_PREVIEW_BYTES = 256;
 
     /**
-     * Currently only one field is mutable: FLAGS.  All others never change once stored in the
-     * database.
+     * Indicates email fields that may change over time.
+     *
+     * Currently only one field is mutable: FLAGS. All others never
+     * change once stored in the database.
      */
     public const Field MUTABLE_FIELDS = Geary.Email.Field.FLAGS;
-    
+
     /**
-     * The fields required to build an RFC822.Message for get_message() and
-     * any attachments.
+     * Indicates the email fields required to build an RFC822.Message.
+     *
+     * @see get_message
      */
     public const Field REQUIRED_FOR_MESSAGE = Geary.Email.Field.HEADER | Geary.Email.Field.BODY;
-    
-    // THESE VALUES ARE PERSISTED.  Change them only if you know what you're doing.
+
+    /**
+     * Specifies specific parts of an email message.
+     *
+     * See the {@link Email.fields} property to determine which parts
+     * an email object currently contains.
+     */
     public enum Field {
+        // THESE VALUES ARE PERSISTED.  Change them only if you know what you're doing.
+
+        /** Denotes no fields. */
         NONE =              0,
+
+        /** The RFC 822 Date header. */
         DATE =              1 << 0,
+
+        /** The RFC 822 From, Sender, and Reply-To headers. */
         ORIGINATORS =       1 << 1,
+
+        /** The RFC 822 To, Cc, and Bcc headers. */
         RECEIVERS =         1 << 2,
+
+        /** The RFC 822 Message-Id, In-Reply-To, and References headers. */
         REFERENCES =        1 << 3,
+
+        /** The RFC 822 Subject header. */
         SUBJECT =           1 << 4,
+
+        /** The list of all RFC 822 headers. */
         HEADER =            1 << 5,
+
+        /** The RFC 822 message body and attachments. */
         BODY =              1 << 6,
+
+        /** The {@link Email.properties} object. */
         PROPERTIES =        1 << 7,
+
+        /** The plain text preview. */
         PREVIEW =           1 << 8,
+
+        /** The {@link Email.email_flags} object. */
         FLAGS =             1 << 9,
-        
-        ENVELOPE =          DATE | ORIGINATORS | RECEIVERS | REFERENCES | SUBJECT,
-        ALL =               DATE | ORIGINATORS | RECEIVERS | REFERENCES | SUBJECT | HEADER | BODY
-                            | PROPERTIES | PREVIEW | FLAGS;
-        
+
+        /**
+         * The union of the primary headers of a message.
+         *
+         * The envelope includes the {@link DATE}, {@link
+         * ORIGINATORS}, {@link RECEIVERS}, {@link REFERENCES}, and
+         * {@link SUBJECT} fields.
+         */
+        ENVELOPE = DATE | ORIGINATORS | RECEIVERS | REFERENCES | SUBJECT,
+
+        /** The union of all email fields. */
+        ALL =      DATE | ORIGINATORS | RECEIVERS | REFERENCES | SUBJECT |
+                   HEADER | BODY | PROPERTIES | PREVIEW | FLAGS;
+
         public static Field[] all() {
             return {
                 DATE,
@@ -108,15 +164,18 @@ public class Geary.Email : BaseObject {
             return builder.str;
         }
     }
-    
+
     /**
-     * id is a unique identifier for the Email in the Folder.  It is guaranteed to be unique for
-     * as long as the Folder is open.  Once closed, guarantees are no longer made.
+     * A unique identifier for the Email in the Folder.
+     *
+     * This is is guaranteed to be unique for as long as the Folder is
+     * open. Once closed, guarantees are no longer made.
      *
-     * This field is always returned, no matter what Fields are used to retrieve the Email.
+     * This field is always returned, no matter what Fields are used
+     * to retrieve the Email.
      */
     public Geary.EmailIdentifier id { get; private set; }
-    
+
     // DATE
     public Geary.RFC822.Date? date { get; private set; default = null; }
 
@@ -154,9 +213,23 @@ public class Geary.Email : BaseObject {
     
     // FLAGS
     public Geary.EmailFlags? email_flags { get; private set; default = null; }
-    
+
+    /**
+     * Specifies the properties that have been populated for this email.
+     *
+     * Since this email object may be a partial representation of a
+     * complete email message, this property lists all parts of the
+     * object that have actually been loaded, as opposed to parts that
+     * are simply missing from the email it represents.
+     *
+     * For example, if this property includes the {@link
+     * Field.SUBJECT} flag, then the {@link subject} property has been
+     * set to reflect the Subject header of the message. Of course,
+     * the subject may then still may be null or empty, if the email
+     * did not specify a subject header.
+     */
     public Geary.Email.Field fields { get; private set; default = Field.NONE; }
-    
+
     private Geary.RFC822.Message? message = null;
     
     public Email(Geary.EmailIdentifier id) {
@@ -279,10 +352,13 @@ public class Geary.Email : BaseObject {
         }
         return search.str;
     }
-    
+
     /**
-     * This method requires the REQUIRED_FOR_MESSAGE fields be present.
-     * If not, EngineError.INCOMPLETE_MESSAGE is thrown.
+     * Constructs a new RFC 822 message from this email.
+     *
+     * This method requires the {@link REQUIRED_FOR_MESSAGE} fields be
+     * present. If not, {@link EngineError.INCOMPLETE_MESSAGE} is
+     * thrown.
      */
     public Geary.RFC822.Message get_message() throws EngineError, RFC822Error {
         if (message != null)
diff --git a/src/engine/api/geary-folder.vala b/src/engine/api/geary-folder.vala
index 95768b0..b167d96 100644
--- a/src/engine/api/geary-folder.vala
+++ b/src/engine/api/geary-folder.vala
@@ -1,5 +1,6 @@
 /*
  * Copyright 2016 Software Freedom Conservancy Inc.
+ * Copyright 2018 Michael Gratton <mike vee net>
  *
  * This software is licensed under the GNU Lesser General Public License
  * (version 2.1 or later).  See the COPYING file in this distribution.
@@ -8,15 +9,32 @@
 /**
  * A Folder represents the basic unit of organization for email.
  *
- * Folders may contain a set of messages, either stored purely locally
+ * Each {@link Account} provides a hierarchical listing of Folders.
+ * Note that while most folders are able to store email messages, some
+ * folders may not and may exist purely to group together folders
+ * below it in the account's folder hierarchy. Folders that can
+ * contain email messages either store these messages purely locally
  * (for example, in the case of an ''outbox'' for mail queued for
  * sending), or as a representation of those found in a mailbox on a
- * remote mail server, such as those provided by an IMAP server. For
- * folders that represent a remote mailbox, messages are cached
- * locally, and the set of cached messages may be a subset of those
- * available in the mailbox, depending on an account's settings. Note
- * that some folders may not be able to contain any messages, and may
- * exist purely to construct a hierarchy.
+ * remote mail server, such as those provided by an IMAP server. Email
+ * messages are represented by the {@link Email} class, and many
+ * folder methods will return collections of these. For folders that
+ * represent a remote mailbox, the mailbox's email are cached locally,
+ * and the set of cached messages may be a subset of those available
+ * in the mailbox, depending on an account's settings. Email messages
+ * may be partially cached, in the case of a new message having just
+ * arrived or a message with many large attachments that was not
+ * completely downloaded.
+ *
+ * Folder objects must be opened (with {@link open_async} before using
+ * most of its methods and should be closed with {@link close_async}
+ * when completed, even if a previous method call has failed with an
+ * IOError. Folders offer various open states indicating when its
+ * "local" (disk or database) connection and "remote" (network)
+ * connections are ready.  Generally the local connection opens first
+ * and the remote connection takes time to establish. When in this
+ * state, Folder's methods still operate, but will only return locally
+ * stored information.
  *
  * The set of locally stored messages is called the folder's
  * ''vector'', and contains generally the most recent message in the
@@ -35,18 +53,6 @@
  * another on the server or in response to user operations such as
  * moving a message.
  *
- * Each {@link Account} offers a hierarchical listing of Folders.
- * Folders must be opened (with {@link open_async} before using most
- * of its methods and should be closed with {@link close_async} when
- * completed, even if a method has failed with an IOError.
- *
- * Folders offer various open states indicating when its "local" (disk
- * or database) connection and "remote" (network) connections are
- * ready.  Generally the local connection opens first and the remote
- * connection takes time to establish.  When in this state, Folder's
- * methods still operate, but will only return locally stored
- * information.
- *
  * This class only offers a small selection of guaranteed
  * functionality (in particular, the ability to list its {@link
  * Email}).  Additional functionality for Folders is indicated by the
@@ -56,9 +62,38 @@
  * @see Geary.SpecialFolderType
  */
 public abstract class Geary.Folder : BaseObject {
+
+    /**
+     * Indicates if a folder has been opened, and if so in which way.
+     */
     public enum OpenState {
+
+        /**
+         * Indicates the folder has not been opened.
+         *
+         * Either no call to {@link open_async} has yet been made, or
+         * an equal number of calls to {@link close_async} have also
+         * been made.
+         */
         CLOSED,
+
+        /**
+         * Indicates the folder has been opened locally only.
+         *
+         * The folder has been opened by a call to {@link open_async},
+         * but if the folder is backed by a remote mailbox, a
+         * connection to the remote mailbox has not yet been
+         * established.
+         */
         LOCAL,
+
+        /**
+         * Indicates the folder has been opened with a remote connection.
+         *
+         * The folder has been opened by a call to {@link open_async},
+         * and a connection to the remote mailbox has also been
+         * made. Local-only folders will never reach this state.
+         */
         REMOTE;
     }
 
@@ -183,17 +218,23 @@ public abstract class Geary.Folder : BaseObject {
             return !is_oldest_to_newest();
         }
     }
-    
+
+    /** The account that owns this folder. */
     public abstract Geary.Account account { get; }
-    
+
+    /** Current properties for this folder. */
     public abstract Geary.FolderProperties properties { get; }
-    
+
+    /** The folder path represented by this object. */
     public abstract Geary.FolderPath path { get; }
-    
+
+    /** Determines the type of this folder. */
     public abstract Geary.SpecialFolderType special_folder_type { get; }
-    
+
+    /** Monitor for notifying of progress when opening the folder. */
     public abstract Geary.ProgressMonitor opening_monitor { get; }
 
+
     /**
      * Fired when the folder moves through stages of being opened.
      *
@@ -207,16 +248,10 @@ public abstract class Geary.Folder : BaseObject {
      * the folder has opened and the count reflects the number of
      * messages in the local store.
      *
-     * If //state// is {@link OpenState.BOTH}, it indicates both the
+     * If //state// is {@link OpenState.REMOTE}, it indicates both the
      * local store and a remote session has been established, and the
-     * count reflects the number of messages on the remote.
-     *
-     * If //state// is {@link OpenState.REMOTE}, it indicates a folder
-     * is not synchronized locally but rather one entirely backed by a
-     * network server.
-     *
-     * In the case of {@link OpenState.BOTH} or {@link
-     * OpenState.REMOTE}, it refers to the authoritative count.
+     * count reflects the number of messages on the remote. This
+     * signal will not be fired with this value for a local-only folder.
      *
      * This signal will never fire with {@link OpenState.CLOSED} as a
      * parameter.
@@ -427,57 +462,78 @@ public abstract class Geary.Folder : BaseObject {
         return (special_folder_type == Geary.SpecialFolderType.NONE)
             ? path.basename : special_folder_type.get_display_name();
     }
-    
-    /**
-     * Returns the state of the Folder's connections to the local and remote stores.
-     */
+
+    /** Determines if a folder has been opened, and if so in which way. */
     public abstract OpenState get_open_state();
 
     /**
      * Marks the folder's operations as being required for use.
      *
-     * The Folder must be opened before most operations may be performed on it.  Depending on the
-     * implementation this might entail opening a network connection or setting the connection to
-     * a particular state, opening a file or database, and so on.
-     *
-     * In the case of a Folder that is aggregating the contents of synchronized folder, it's possible
-     * for this method to complete even though all internal opens haven't completed.  The "opened"
-     * signal is the final say on when a Folder is fully opened with its OpenState parameter
-     * indicating how open it really is.  In general, a Folder's local store will open immediately
-     * while it may take time (if ever) for the remote state to open.  Thus, it's possible for
-     * the "opened" signal to fire some time *after* this method completes.
-     *
-     * {@link OpenFlags.NO_DELAY} may be passed to force an immediate opening of the remote folder.
-     * This still will not occur in the context of the open_async call, but will initiate the
-     * connection immediately.  Use this only when it's known that remote calls or remote
-     * notifications to the Folder are imminent or monitoring the Folder is vital (such as with the
-     * Inbox).
-     *
-     * However, even if the method returns before the Folder's OpenState is BOTH, this Folder is
-     * ready for operation if this method returns without error.  The messages the folder returns
-     * may not reflect the full state of the Folder, however, and returned emails may subsequently
-     * have their state changed (such as their position).  Making a call that requires
-     * accessing the remote store before OpenState.BOTH has been signalled will result in that
-     * call blocking until the remote is open or an error state has occurred.  It's also possible for
-     * the command to return early without waiting, depending on prior information of the folder.
-     * See list_email_async() for special notes on its operation.  Also see wait_for_remote_async().
-     *
-     * If there's an error while opening, "open-failed" will be fired.  (See that signal for more
-     * information on how many times it may fire, and when.)  To prevent the Folder from going into
-     * a halfway state, it will immediately schedule a close_async() to cleanup, and those
-     * associated signals will be fired as well.
-     *
-     * If the Folder has been opened previously, an internal open count is incremented and the
-     * method returns.  There are no other side-effects.  This means it's possible for the
-     * open_flags parameter to be ignored.  See the returned result for more information.
-     *
-     * A Folder may be reopened after it has been closed.  This allows for Folder objects to be
-     * emitted by the Account object cheaply, but the client should only have a few open at a time,
-     * as each may represent an expensive resource (such as a network connection).
+     * A folder object must be opened before most operations may be
+     * performed on it. Depending on the folder implementation this
+     * might entail opening a network connection or setting the
+     * connection to a particular state, opening a file or database,
+     * and so on. In general, a Folder's local store should open
+     * immediately, hence if this call returns with error, {@link
+     * get_open_state} should return {@link OpenState.LOCAL}.
+     *
+     * For folders that are backed by a remote mailbox, it may take
+     * time for a remote connection to be established (if ever), and
+     * so it is possible for this method to complete even though a
+     * remote connection is not available. In this case the folder's
+     * state and the email messages the its contains are backed by a
+     * local cache, and may not reflect the full state of the remote
+     * mailbox. Hence both folder and email state may subsequently be
+     * changed (such as their position) after the remote connection
+     * has been established and the local and remote stores have been
+     * synchronised. Use signals such as {@link email_appended} to be
+     * notified of such changes.
+     *
+     * Connecting to the {@link opened} signal can be used to be
+     * notified when a remote connection has been established. Making
+     * a method call on a folder that requires accessing the remote
+     * mailbox before {@link OpenState.REMOTE} has been sent via this
+     * signal will result in that call blocking until the remote is
+     * open, the folder closes, or an error occurs. However it is also
+     * possible for some methods to return early without waiting,
+     * depending on prior information of the folder. See {@link
+     * list_email_by_id_async} for special notes on its
+     * operation. Also see {@link wait_for_remote_async}.
+     *
+     * In some cases, establishing a remote connection may be
+     * performed lazily, that is only when first needed. If however
+     * {@link OpenFlags.NO_DELAY} is passed as an argument it will
+     * instead force an immediate opening of the remote
+     * connection. This still will not occur in the context of the
+     * this method all call, but it will ensure the a connection is
+     * initiated immediately. Since establishing remote connections is
+     * costly, use this only when it's known that remote calls or
+     * remote notifications to the Folder are imminent or monitoring
+     * the Folder is vital (such as with the Inbox).
+     *
+     * If the Folder has been opened by a call to this method
+     * previously, an internal open count is incremented and the
+     * method returns. There are no other side-effects. This means
+     * it's possible for the open_flags parameter to be ignored. See
+     * the returned result for more information.
+     *
+     * A Folder may safely be reopened after it has been closed. This
+     * allows for Folder objects to be emitted by the Account object
+     * cheaply, but the client should only have a few open at a time,
+     * as each may represent an expensive resource (such as a network
+     * connection).
+     *
+     * If there is an error while opening, "open-failed" will be
+     * fired.  (See that signal for more information on how many times
+     * it may fire, and when.)  To prevent the Folder from going into
+     * a halfway state, it will immediately schedule a close_async()
+     * to cleanup, and those associated signals will be fired as well.
      *
      * Returns false if already opened.
      */
-    public abstract async bool open_async(OpenFlags open_flags, Cancellable? cancellable = null) throws 
Error;
+    public abstract async bool open_async(OpenFlags open_flags,
+                                          Cancellable? cancellable = null)
+        throws Error;
 
     /**
      * Blocks waiting for the folder to establish a remote session.
@@ -492,19 +548,22 @@ public abstract class Geary.Folder : BaseObject {
     /**
      * Marks one use of the folder's operations as being completed.
      *
-     * The Folder should be closed when operations on it are concluded.  Depending on the
-     * implementation this might entail closing a network connection or reverting it to another
-     * state, or closing file handles or database connections.
-     *
-     * If the Folder is open, an internal open count is decremented.  If it remains above zero, the
-     * method returns with no other side-effects.  If it decrements to zero, the Folder is closed,
-     * tearing down network connections, closing files, and so forth.  See "closed" for signals
-     * indicating the closing states.
-     *
-     * Returns true if the open count decrements to zero and the folder is ''closing''.  Use
-     * {@link wait_for_close_async} to block until the folder is completely closed.  Otherwise,
-     * returns false.  Note that this semantic is slightly different than the result code for
-     * {@link open_async}.
+     * The folder must be closed when operations on it are concluded.
+     * Depending on the implementation this might entail closing a
+     * network connection or reverting it to another state, or closing
+     * file handles or database connections.
+     *
+     * If the folder is open, an internal open count is decremented.
+     * If it remains above zero, the method returns with no other
+     * side-effects.  If it decrements to zero, the folder will start
+     * to close tearing down network connections, closing files, and
+     * so-forth. The {@link closed} signal can be used to be notified
+     * of progress closing the folder.  Use {@link
+     * wait_for_close_async} to block until the folder is completely
+     * closed.
+     *
+     * Returns true if the open count decrements to zero and the
+     * folder is closing, or if it is already closed.
      *
      * @see open_async
      */
diff --git a/src/engine/rfc822/rfc822-message.vala b/src/engine/rfc822/rfc822-message.vala
index 5b6f373..b78078c 100644
--- a/src/engine/rfc822/rfc822-message.vala
+++ b/src/engine/rfc822/rfc822-message.vala
@@ -6,7 +6,15 @@
  * (version 2.1 or later).  See the COPYING file in this distribution.
  */
 
+/**
+ * An RFC-822 style email message.
+ *
+ * Unlike {@link Email}, these objects are always a complete
+ * representation of an email message, and contain no information
+ * other than what RFC-822 and its successor RFC documents specify.
+ */
 public class Geary.RFC822.Message : BaseObject {
+
     /**
      * This delegate is an optional parameter to the body constructers that allows callers
      * to process arbitrary non-text, inline MIME parts.
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]