[folks/648811-dummy-backend-rebase1: 38/48] dummy: Documentation updates

[Philip Withnall <pwithnall src gnome org>]

commit fc63432316984bcfd17f3047ff15762562b3e1e3
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Thu Nov 7 08:21:08 2013 +0000

    dummy: Documentation updates

 backends/dummy/lib/dummy-persona-store.vala |   13 +++++++++++++
 1 files changed, 13 insertions(+), 0 deletions(-)
---
diff --git a/backends/dummy/lib/dummy-persona-store.vala b/backends/dummy/lib/dummy-persona-store.vala
index b78328f..eca0420 100644
--- a/backends/dummy/lib/dummy-persona-store.vala
+++ b/backends/dummy/lib/dummy-persona-store.vala
@@ -38,6 +38,19 @@ using GLib;
  * backing store. Calls to these mock methods effect state changes in the store
  * which are visible in the normal libfolks API.
  *
+ * The main action performed with a dummy persona store is to change its set of
+ * personas, adding and removing them dynamically to test client-side behaviour.
+ * The client-side APIs ({ link PersonaStore.add_persona_from_details} and
+ * { link PersonaStore.remove_persona}) should //not// be used for this.
+ * Instead, the mock APIs should be used:
+ * { link FolksDummy.PersonaStore.freeze_personas_changed},
+ * { link FolksDummy.PersonaStore.register_personas},
+ * { link FolksDummy.PersonaStore.unregister_personas} and
+ * { link FolksDummy.PersonaStore.thaw_personas_changed}. These can be used to
+ * build up complex { link PersonaStore.personas_changed} signal emissions,
+ * which are only emitted after the final call to
+ * { link FolksDummy.PersonaStore.thaw_personas_changed}.
+ *
  * The API in { link FolksDummy} is unstable and may change wildly. It is
  * designed mostly for use by libfolks unit tests.
  *