[geary/mjog/invert-folder-class-hierarchy] engine: Better specify contract for RemoteFolder properties

[Michael Gratton <mjog src gnome org>]

commit 61d6d68ee2824f3270ecdb4dd3552cf30a45dd4d
Author: Michael Gratton <mike vee net>
Date:   Thu Mar 4 21:18:25 2021 +1100

    engine: Better specify contract for RemoteFolder properties

 src/engine/api/geary-remote-folder.vala            | 31 +++++++++++++++-------
 .../imap-engine/imap-engine-minimal-folder.vala    | 12 ++++-----
 test/mock/mock-remote-folder.vala                  | 10 +++----
 3 files changed, 32 insertions(+), 21 deletions(-)
---
diff --git a/src/engine/api/geary-remote-folder.vala b/src/engine/api/geary-remote-folder.vala
index e280289e7..b58485ade 100644
--- a/src/engine/api/geary-remote-folder.vala
+++ b/src/engine/api/geary-remote-folder.vala
@@ -91,27 +91,38 @@ public interface Geary.RemoteFolder : Folder {
     }
 
 
-    /** Last known remote properties for this folder. */
-    public abstract RemoteProperties remote_properties { get; }
-
     /**
-     * Indicates if the folder is checking for remote changes to email.
+     * Last known properties of this folder's remote mailbox.
      *
-     * @see start_monitoring
-     * @see stop_monitoring
+     * This property is not guaranteed to be accurate at all times. It
+     * is only updated whenever a connection to the remote folder is
+     * established, i.e. by {@link start_monitoring}, {@link
+     * synchronise}, {@link expand_vector} and others, and in response
+     * to notifications from the server.
+     *
+     * Note that remote properties may change even when there is no
+     * current connection to this remote folder (that is, if {@link
+     * is_connected} is false), since another connection may have
+     * provided updated information.
      */
-    public abstract bool is_monitoring { get; }
+    public abstract RemoteProperties remote_properties { get; }
 
     /**
      * Indicates if the folder's local vector contains all remote email.
      *
      * This property is not guaranteed to be accurate at all times. It
-     * is only updated whenever a connection to the remote folder is
-     * established, i.e. by {@link start_monitoring}, {@link
-     * synchronise}, {@link expand_vector} and others.
+     * is only updated at the same times as {@link remote_properties}.
      */
     public abstract bool is_fully_expanded { get; }
 
+    /**
+     * Indicates if the folder is checking for remote changes to email.
+     *
+     * @see start_monitoring
+     * @see stop_monitoring
+     */
+    public abstract bool is_monitoring { get; }
+
 
     /**
      * Starts the folder checking for remote changes to email.
diff --git a/src/engine/imap-engine/imap-engine-minimal-folder.vala 
b/src/engine/imap-engine/imap-engine-minimal-folder.vala
index c68da83a6..30d649ccf 100644
--- a/src/engine/imap-engine/imap-engine-minimal-folder.vala
+++ b/src/engine/imap-engine/imap-engine-minimal-folder.vala
@@ -78,18 +78,18 @@ private class Geary.ImapEngine.MinimalFolder : BaseObject,
         get { return this.local_folder.properties; }
     }
 
-    /** {@inheritDoc} */
-    public bool is_monitoring {
-        get { return this._is_monitoring; }
-    }
-    private bool _is_monitoring = false;
-
     /** {@inheritDoc} */
     public bool is_fully_expanded {
         get { return this._is_fully_expanded; }
     }
     private bool _is_fully_expanded = false;
 
+    /** {@inheritDoc} */
+    public bool is_monitoring {
+        get { return this._is_monitoring; }
+    }
+    private bool _is_monitoring = false;
+
     /** {@inheritDoc} */
     public Logging.Source? logging_parent {
         get { return this.account; }
diff --git a/test/mock/mock-remote-folder.vala b/test/mock/mock-remote-folder.vala
index e64493ad6..08907fd55 100644
--- a/test/mock/mock-remote-folder.vala
+++ b/test/mock/mock-remote-folder.vala
@@ -63,16 +63,16 @@ public class Mock.RemoteFolder : GLib.Object,
         get { return this._used_as; }
     }
 
-    public bool is_monitoring {
-        get { return this._is_monitoring; }
-    }
-    private bool _is_monitoring = false;
-
     public bool is_fully_expanded {
         get { return this._is_fully_expanded; }
     }
     private bool _is_fully_expanded = false;
 
+    public bool is_monitoring {
+        get { return this._is_monitoring; }
+    }
+    private bool _is_monitoring = false;
+
     public Geary.Logging.Source? logging_parent {
         get { return this.account; }
     }