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

[Philip Withnall <pwithnall src gnome org>]

commit 582c5c741e51d9fce145245b6bc79fe7282d1660
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Thu Nov 7 08:11:23 2013 +0000

    dummy: Documentation updates

 backends/dummy/lib/dummy-backend.vala       |    3 +++
 backends/dummy/lib/dummy-fat-persona.vala   |    3 +++
 backends/dummy/lib/dummy-persona-store.vala |   16 ++++++++++++----
 backends/dummy/lib/dummy-persona.vala       |    3 +++
 4 files changed, 21 insertions(+), 4 deletions(-)
---
diff --git a/backends/dummy/lib/dummy-backend.vala b/backends/dummy/lib/dummy-backend.vala
index f4fd647..16e2f26 100644
--- a/backends/dummy/lib/dummy-backend.vala
+++ b/backends/dummy/lib/dummy-backend.vala
@@ -44,6 +44,9 @@ extern const string BACKEND_NAME;
  * { link Backend.enable_persona_store}, { link Backend.disable_persona_store}
  * and { link Backend.set_persona_stores}.
  *
+ * The API in { link FolksDummy} is unstable and may change wildly. It is
+ * designed mostly for use by libfolks unit tests.
+ *
  * @since UNRELEASED
  */
 public class FolksDummy.Backend : Folks.Backend
diff --git a/backends/dummy/lib/dummy-fat-persona.vala b/backends/dummy/lib/dummy-fat-persona.vala
index 54ef95c..013c2bf 100644
--- a/backends/dummy/lib/dummy-fat-persona.vala
+++ b/backends/dummy/lib/dummy-fat-persona.vala
@@ -45,6 +45,9 @@ using GLib;
  * { link FatPersona.update_nickname} to simulate the user editing a contact’s
  * nickname in an online address book which is being exposed to libfolks.
  *
+ * The API in { link FolksDummy} is unstable and may change wildly. It is
+ * designed mostly for use by libfolks unit tests.
+ *
  * @since UNRELEASED
  */
 public class FolksDummy.FatPersona : FolksDummy.Persona,
diff --git a/backends/dummy/lib/dummy-persona-store.vala b/backends/dummy/lib/dummy-persona-store.vala
index 34f6f9d..f8e28b9 100644
--- a/backends/dummy/lib/dummy-persona-store.vala
+++ b/backends/dummy/lib/dummy-persona-store.vala
@@ -27,12 +27,20 @@ using GLib;
 /**
  * A persona store which allows { link FolksDummy.Persona}s to be
  * programmatically created and manipulated, for the purposes of testing the
- * core of libfolks itself.
+ * core of libfolks itself. This should not be used in user-visible
+ * applications.
  *
- * TODO: Mock functions
- * TODO: Unstable API
+ * There are two sides to this class’ interface: the methods and properties
+ * declared by { link Folks.PersonaStore}, which form the normal libfolks
+ * persona store API; and the mock methods and properties (such as
+ * { link FolksDummy.PersonaStore.add_persona_from_details_mock}) which are
+ * intended to be used by test driver code to simulate the behaviour of a real
+ * backing store. Calls to these mock methods effect state changes in the store
+ * which are visible in the normal libfolks API.
+ *
+ * The API in { link FolksDummy} is unstable and may change wildly. It is
+ * designed mostly for use by libfolks unit tests.
  *
- * TODO
  *
  * TODO: trust_level and is_user_set_default can be set as normal properties
  *
diff --git a/backends/dummy/lib/dummy-persona.vala b/backends/dummy/lib/dummy-persona.vala
index b02905a..071cbe0 100644
--- a/backends/dummy/lib/dummy-persona.vala
+++ b/backends/dummy/lib/dummy-persona.vala
@@ -41,6 +41,9 @@ using GLib;
  * { link FolksDummy.Persona} have a configurable delay before taking effect,
  * which can be controlled by { link FolksDummy.Persona.property_change_delay}.
  *
+ * The API in { link FolksDummy} is unstable and may change wildly. It is
+ * designed mostly for use by libfolks unit tests.
+ *
  * @since UNRELEASED
  */
 public class FolksDummy.Persona : Folks.Persona