[folks/648811-dummy-backend-rebase1: 32/41] dummy: Documentation updates

[Philip Withnall <pwithnall src gnome org>]

commit 2a738f50b672f42c61271612b3fb6751fc91461d
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Wed Nov 6 18:27:39 2013 +0000

    dummy: Documentation updates

 backends/dummy/lib/dummy-fat-persona.vala |   36 +++++++---
 backends/dummy/lib/dummy-persona.vala     |  115 ++++++++++++++++++++++------
 2 files changed, 116 insertions(+), 35 deletions(-)
---
diff --git a/backends/dummy/lib/dummy-fat-persona.vala b/backends/dummy/lib/dummy-fat-persona.vala
index 63cb03d..54ef95c 100644
--- a/backends/dummy/lib/dummy-fat-persona.vala
+++ b/backends/dummy/lib/dummy-fat-persona.vala
@@ -26,12 +26,24 @@ using Gee;
 using GLib;
 
 /**
- * A persona subclass which represents a single dummy contact. TODO
+ * A persona subclass representing a single ‘fat’ contact.
  *
- * Each { link Dummy.Persona} instance represents a single dummy { link E.Contact}.
- * When the contact is modified (either by this folks client, or a different
- * client), the { link Dummy.Persona} remains the same, but is assigned a new
- * { link E.Contact}. It then updates its properties from this new contact.
+ * This mocks up a ‘fat’ persona which implements all the available property
+ * interfaces provided by libfolks. This is in contrast with
+ * { link FolksDummy.Persona}, which provides a base class implementing none of
+ * libfolks’ interfaces.
+ *
+ * The fat dummy persona can be used to simulate a persona from most libfolks
+ * backends, if writing a custom { link FolksDummy.Persona} subclass is not an
+ * option.
+ *
+ * There are two sides to this class’ interface: the normal methods required by
+ * the libfolks ‘details’ interfaces, such as { link FatPersona.change_gender},
+ * and the backend methods which should be called by test driver code to
+ * simulate changes in the backing store providing this persona, such as
+ * { link FatPersona.update_gender}. For example, test driver code should call
+ * { link FatPersona.update_nickname} to simulate the user editing a contact’s
+ * nickname in an online address book which is being exposed to libfolks.
  *
  * @since UNRELEASED
  */
@@ -54,14 +66,17 @@ public class FolksDummy.FatPersona : FolksDummy.Persona,
     WebServiceDetails
 {
   /**
-   * Create a new persona.
+   * Create a new ‘fat’ persona.
    *
-   * Create a new persona for the { link PersonaStore} ``store``, representing
-   * the dummy contact given by ``contact``. TODO
+   * Create a new persona for the { link PersonaStore} ``store``, with the given
+   * construct-only properties.
    *
    * @param store the store which will contain the persona
-   * @param contact_id TODO
-   * @param is_user TODO
+   * @param contact_id a unique free-form string identifier for the persona
+   * @param is_user ``true`` if the persona represents the user, ``false``
+   * otherwise
+   * @param linkable_properties an array of names of the properties which should
+   * be used for linking this persona to others
    *
    * @since UNRELEASED
    */
@@ -559,6 +574,7 @@ public class FolksDummy.FatPersona : FolksDummy.Persona,
     }
 
   private DateTime? _birthday = null;
+
   /**
    * { inheritDoc}
    *
diff --git a/backends/dummy/lib/dummy-persona.vala b/backends/dummy/lib/dummy-persona.vala
index dfe0c68..b02905a 100644
--- a/backends/dummy/lib/dummy-persona.vala
+++ b/backends/dummy/lib/dummy-persona.vala
@@ -23,12 +23,23 @@ using Gee;
 using GLib;
 
 /**
- * A persona subclass which represents a single contact. TODO
+ * A persona subclass representing a single contact.
  *
- * Each { link Dummy.Persona} instance represents a single dummy { link E.Contact}.
- * When the contact is modified (either by this folks client, or a different
- * client), the { link Dummy.Persona} remains the same, but is assigned a new
- * { link E.Contact}. It then updates its properties from this new contact.
+ * This mocks up a ‘thin’ persona which implements none of the available
+ * property interfaces provided by libfolks, and is designed as a base class to
+ * be subclassed by personas which will implement one or more of these
+ * interfaces. For example, { link FolksDummy.FatPersona} is one such subclass
+ * which implements all available interfaces.
+ *
+ * There are two sides to this class’ interface: the normal methods required by
+ * { link Folks.Persona}, such as { link Persona.linkable_property_to_links},
+ * and the backend methods which should be called by test driver code to
+ * simulate changes in the backing store providing this persona, such as
+ * { link FolksDummy.Persona.update_writeable_properties}.
+ *
+ * All property changes for contact details of subclasses of
+ * { link FolksDummy.Persona} have a configurable delay before taking effect,
+ * which can be controlled by { link FolksDummy.Persona.property_change_delay}.
  *
  * @since UNRELEASED
  */
@@ -61,12 +72,20 @@ public class FolksDummy.Persona : Folks.Persona
   /**
    * Create a new persona.
    *
-   * Create a new persona for the { link PersonaStore} ``store``, representing
-   * the dummy contact given by ``contact``. TODO
+   * Create a new persona for the { link PersonaStore} ``store``, with the given
+   * construct-only properties.
+   *
+   * The persona’s { link Persona.writeable_properties} are initialised to the
+   * given ``store``’s { link PersonaStore.always_writeable_properties}. They
+   * may be updated afterwards using
+   * { link FolksDummy.Persona.update_writeable_properties}.
    *
    * @param store the store which will contain the persona
-   * @param contact_id TODO
-   * @param is_user TODO
+   * @param contact_id a unique free-form string identifier for the persona
+   * @param is_user ``true`` if the persona represents the user, ``false``
+   * otherwise
+   * @param linkable_properties an array of names of the properties which should
+   * be used for linking this persona to others
    *
    * @since UNRELEASED
    */
@@ -94,7 +113,6 @@ public class FolksDummy.Persona : Folks.Persona
   public override void linkable_property_to_links (string prop_name,
       Folks.Persona.LinkablePropertyCallback callback)
     {
-      /* TODO */
       if (prop_name == "im-addresses")
         {
           var persona = this as ImDetails;
@@ -162,45 +180,92 @@ public class FolksDummy.Persona : Folks.Persona
 
 
   /**
-   * TODO
+   * Update the persona’s set of writeable properties.
+   *
+   * Update the { link Persona.writeable_properties} property to contain the
+   * union of { link PersonaStore.always_writeable_properties} from the
+   * persona’s store, and the given ``writeable_properties``.
+   *
+   * This should be used to simulate a change in the backing store for the
+   * persona which affects the writeability of one or more of its properties.
    *
    * @since UNRELEASED
    */
   public void update_writeable_properties (string[] writeable_properties)
     {
-      /* TODO: Don't update if there's no change. */
-      var new_length = this.store.always_writeable_properties.length +
-          writeable_properties.length;
-      this._writeable_properties = new string[new_length];
-      int i = 0;
+      var new_writeable_properties = new HashSet<string> ();
 
       foreach (var p in this.store.always_writeable_properties)
+          new_writeable_properties.add (p);
+      foreach (var p in writeable_properties)
+          new_writeable_properties.add (p);
+
+      /* Check for changes. */
+      var changed = false;
+
+      if (this._writeable_properties.length != new_writeable_properties.size)
         {
-          this._writeable_properties[i++] = p;
+          changed = true;
         }
-      foreach (var p in writeable_properties)
+      else
         {
-          this._writeable_properties[i++] = p;
+          foreach (var p in this._writeable_properties)
+            {
+              if (new_writeable_properties.contains (p) == false)
+                {
+                  changed = true;
+                  break;
+                }
+            }
         }
 
-      this.notify_property ("writeable-properties");
+      if (changed == true)
+        {
+          this._writeable_properties = new_writeable_properties.to_array ();
+          this.notify_property ("writeable-properties");
+        }
     }
 
   /**
-   * TODO (in milliseconds)
+   * Delay between property changes and notifications.
+   *
+   * This sets an optional delay between client code requesting a property
+   * change (e.g. by calling { link NameDetails.change_nickname}) and the
+   * property change taking place and a { link Object.notify} signal being
+   * emitted for it.
+   *
+   * Delays are in milliseconds. Negative delays mean that property change
+   * notifications happen synchronously in the change method. A delay of 0
+   * means that property change notifications happen in an idle callback
+   * immediately after the change method. A positive delay means that property
+   * change notifications happen that many milliseconds after the change method
+   * is called.
    *
    * @since UNRELEASED
    */
   protected int property_change_delay { get; set; }
 
-  /* TODO */
+  /**
+   * Callback to effect a property change in a backing store.
+   *
+   * This is called by { link FolksDummy.Persona.change_property} after the
+   * { link FolksDummy.Persona.property_change_delay} has expired. It must
+   * effect the property change in the simulated backing store, for example by
+   * calling an ‘update’ method such as { link FatPersona.update_nickname}.
+   *
+   * @since UNRELEASED
+   */
   protected delegate void ChangePropertyCallback ();
 
   /**
-   * TODO
+   * Change a property in the simulated backing store.
+   *
+   * This triggers a property change in the simulated backing store, applying
+   * the current { link FolksDummy.Persona.property_change_delay} before calling
+   * the given ``callback`` which should actually effect the property change.
    *
-   * @param property_name TODO
-   * @param callback TODO
+   * @param property_name name of the property being changed
+   * @param callback callback to call once the change delay has passed
    * @since UNRELEASED
    */
   protected async void change_property (string property_name,