[folks] Document recently-added TestCase subclasses

[Simon McVittie <smcv src gnome org>]

commit ed877652b0f51fa1c28e95fab5f5974b1e880c9b
Author: Simon McVittie <simon mcvittie collabora co uk>
Date:   Mon Mar 18 12:06:00 2013 +0000

    Document recently-added TestCase subclasses
    
    They currently assume that they will be wrapped in with-session-bus*.sh.
    
    Bug: https://bugzilla.gnome.org/show_bug.cgi?id=695381
    Signed-off-by: Simon McVittie <simon mcvittie collabora co uk>
    Reviewed-by: Philip Withnall <philip tecnocode co uk>

 tests/lib/eds/test-case.vala          |   27 +++++++++
 tests/lib/key-file/test-case.vala     |   14 +++++
 tests/lib/libsocialweb/test-case.vala |   17 ++++++
 tests/lib/telepathy/test-case.vala    |   99 +++++++++++++++++++++++++++++++++
 tests/lib/test-case.vala              |   40 +++++++++++--
 tests/lib/tracker/test-case.vala      |   21 +++++++
 6 files changed, 211 insertions(+), 7 deletions(-)
---
diff --git a/tests/lib/eds/test-case.vala b/tests/lib/eds/test-case.vala
index 49bcab1..8ae92aa 100644
--- a/tests/lib/eds/test-case.vala
+++ b/tests/lib/eds/test-case.vala
@@ -22,8 +22,22 @@
  *      Simon McVittie <simon mcvittie collabora co uk>
  */
 
+/**
+ * A test case whose private D-Bus session contains the necessary daemons
+ * for an Evolution address-book.
+ *
+ * FIXME: For now, this relies on running under with-session-bus-eds.sh
+ * with AVATAR_FILE_PATH and FOLKS_BACKEND_PATH set.
+ */
 public class EdsTest.TestCase : Folks.TestCase
 {
+  /**
+   * An EDS backend, normally non-null between set_up() and tear_down().
+   *
+   * If this is non-null, the subclass is expected to have called
+   * its set_up() method at some point before tear_down() is reached.
+   * This usually happens in create_backend().
+   */
   public EdsTest.Backend? eds_backend = null;
 
   public TestCase (string name)
@@ -42,12 +56,25 @@ public class EdsTest.TestCase : Folks.TestCase
       this.configure_primary_store ();
     }
 
+  /**
+   * Virtual method to create and set up the EDS backend.
+   * Called from set_up(); may be overridden to not create the backend,
+   * or to create it but not set it up.
+   *
+   * Subclasses may chain up, but are not required to so.
+   */
   public virtual void create_backend ()
     {
       this.eds_backend = new EdsTest.Backend ();
       ((!) this.eds_backend).set_up ();
     }
 
+  /**
+   * Virtual method to configure ``FOLKS_PRIMARY_STORE`` to point to
+   * our //eds_backend//.
+   *
+   * Subclasses may chain up, but are not required to so.
+   */
   public virtual void configure_primary_store ()
     {
       /* By default, configure EDS as the primary store. */
diff --git a/tests/lib/key-file/test-case.vala b/tests/lib/key-file/test-case.vala
index a804466..762508b 100644
--- a/tests/lib/key-file/test-case.vala
+++ b/tests/lib/key-file/test-case.vala
@@ -20,8 +20,22 @@
  *      Simon McVittie <simon mcvittie collabora co uk>
  */
 
+/**
+ * A test case for the key-file backend, which is configured as the
+ * primary store and as the only backend allowed.
+ */
 public class KfTest.TestCase : Folks.TestCase
 {
+  /**
+   * The key-file test backend.
+   *
+   * For compatibility with Folks' existing tests' assumptions, this
+   * class creates this object but does not call its set_up() or
+   * tear_down() methods.
+   *
+   * FIXME: ideally this should be per-test, created in set_up(),
+   * and torn down in tear_down(). This would require making it nullable.
+   */
   public KfTest.Backend kf_backend;
 
   public TestCase (string name)
diff --git a/tests/lib/libsocialweb/test-case.vala b/tests/lib/libsocialweb/test-case.vala
index f9a05d1..b730078 100644
--- a/tests/lib/libsocialweb/test-case.vala
+++ b/tests/lib/libsocialweb/test-case.vala
@@ -22,8 +22,22 @@
  *      Simon McVittie <simon mcvittie collabora co uk>
  */
 
+/**
+ * A test case for the libsocialweb backend. Folks is configured
+ * to use that backend and no others, with no primary store.
+ *
+ * FIXME: for now, this relies on being run under with-session-bus.sh
+ * with no activatable services.
+ */
 public class LibsocialwebTest.TestCase : Folks.TestCase
 {
+  /**
+   * The libsocialweb test backend, or null outside the period from
+   * set_up() to tear_down().
+   *
+   * If this is non-null, the subclass is expected to have called
+   * its set_up() method at some point before tear_down() is reached.
+   */
   public LibsocialwebTest.Backend? lsw_backend = null;
 
   public TestCase (string name)
@@ -34,6 +48,9 @@ public class LibsocialwebTest.TestCase : Folks.TestCase
       Environment.set_variable ("FOLKS_PRIMARY_STORE", "", true);
     }
 
+  /**
+   * Set up the libsocialweb test backend and wait for it to become ready.
+   */
   public override void set_up ()
     {
       base.set_up ();
diff --git a/tests/lib/telepathy/test-case.vala b/tests/lib/telepathy/test-case.vala
index ca1e503..b5c898f 100644
--- a/tests/lib/telepathy/test-case.vala
+++ b/tests/lib/telepathy/test-case.vala
@@ -22,12 +22,59 @@
  *      Simon McVittie <simon mcvittie collabora co uk>
  */
 
+/**
+ * A test case with a Telepathy backend (used to test the Telepathy
+ * backend specifically), and optionally also a keyfile backend
+ * (used to test Folks in general - see //MixedTestCase//).
+ *
+ * Folks is configured to use the Telepathy backend, with no primary store,
+ * unless //use_keyfile_too// is set.
+ *
+ * FIXME: for now, this relies on being run under with-session-bus.sh
+ * with no activatable services.
+ */
 public class TpfTest.TestCase : Folks.TestCase
 {
+  /**
+   * The key-file backend, or null if a test case has overridden
+   * create_kf_backend() to avoid creating it, or has left
+   * //use_keyfile_too// set to false.
+   *
+   * For the moment this is created in the constructor and freed
+   * in the destructor; ideally those would move into set_up() and
+   * tear_down() at some point.
+   *
+   * If this is non-null, the subclass is expected to have called
+   * its set_up() method at some point before tear_down() is reached.
+   */
   public KfTest.Backend? kf_backend = null;
+
+  /**
+   * The Telepathy backend, or null if a test case has overridden
+   * create_tp_backend() to avoid creating it.
+   *
+   * If this is non-null, the subclass is expected to have called
+   * its set_up() method at some point before tear_down() is reached.
+   */
   public TpTests.Backend? tp_backend = null;
+
+  /**
+   * An account used by the //tp_backend//, or null if a test case
+   * has overridden set_up_tp() to avoid creating it.
+   *
+   * If non-null when tear_down() is reached, this account will be
+   * removed automatically.
+   */
   public void *account_handle = null;
 
+  /**
+   * If true, Folks will be configured to use a key-file as its primary
+   * store, and allow both Telepathy and the key-file to be loaded.
+   * This is used to test Folks in general (e.g. the IndividualAggregator).
+   *
+   * If false, Folks will be configured to use Telepathy only, with no
+   * primary store. This is used to test the Telepathy backend.
+   */
   public virtual bool use_keyfile_too
     {
       get
@@ -36,6 +83,11 @@ public class TpfTest.TestCase : Folks.TestCase
         }
     }
 
+  /**
+   * Set ``FOLKS_BACKENDS_ALLOWED`` and ``FOLKS_PRIMARY_STORE``,
+   * and create the backends if appropriate (although the latter should
+   * ideally move into set_up()).
+   */
   public TestCase (string name)
     {
       base (name);
@@ -57,12 +109,27 @@ public class TpfTest.TestCase : Folks.TestCase
       this.create_tp_backend ();
     }
 
+  /**
+   * Virtual method to create the keyfile backend. Currently called by
+   * the constructor (once per process), but might move into set_up() later.
+   *
+   * The default implementation respects //use_keyfile_too//. Subclasses
+   * can override this to never, or always, create this backend.
+   *
+   * Subclasses may chain up, but are not required to so.
+   */
   public virtual void create_kf_backend ()
     {
       if (use_keyfile_too)
         this.kf_backend = new KfTest.Backend ();
     }
 
+  /**
+   * Virtual method to create the Telepathy backend. Currently called by
+   * the constructor (once per process), but might move into set_up() later.
+   *
+   * Subclasses may chain up, but are not required to so.
+   */
   public virtual void create_tp_backend ()
     {
       this.tp_backend = new TpTests.Backend ();
@@ -75,6 +142,19 @@ public class TpfTest.TestCase : Folks.TestCase
       this.set_up_kf ();
     }
 
+  /**
+   * Virtual method to set up the Telepathy backend, called from
+   * set_up(). The default implementation sets it up and adds one account,
+   * storing its handle in //account_handle//.
+   *
+   * Subclasses may override this to avoid setting up any accounts, to
+   * set up more than one account, or to avoid setup at this stage
+   * (deferring it until the test itself). However, if tp_backend
+   * is not null at tear_down(), the subclass is expected to have called
+   * set_up() on it at some point.
+   *
+   * Subclasses may chain up, but are not required to so.
+   */
   public virtual void set_up_tp ()
     {
       if (this.tp_backend != null)
@@ -87,6 +167,17 @@ public class TpfTest.TestCase : Folks.TestCase
         }
     }
 
+  /**
+   * Virtual method to set up the key-file backend, called from
+   * set_up(). The default implementation sets it up using an empty
+   * key-file, unless it has not been created. Subclasses may override
+   * this to set it up with different contents, or to avoid setup
+   * altogether (deferring it until the test itself). However, if kf_backend
+   * is not null at tear_down(), the subclass is expected to have called
+   * set_up() on it at some point.
+   *
+   * Subclasses may chain up, but are not required to so.
+   */
   public virtual void set_up_kf ()
     {
       if (this.kf_backend != null)
@@ -117,6 +208,14 @@ public class TpfTest.TestCase : Folks.TestCase
     }
 }
 
+/**
+ * A test-case for the combination of Telepathy and a key-file,
+ * used to test things like the IndividualAggregator. This is just
+ * TestCase with //use_keyfile_too// overridden to true.
+ *
+ * Folks is configured to use the Telepathy and key-file backends,
+ * with the latter as its primary store.
+ */
 public class TpfTest.MixedTestCase : TpfTest.TestCase
 {
   public override bool use_keyfile_too
diff --git a/tests/lib/test-case.vala b/tests/lib/test-case.vala
index f0c1590..8abfbfe 100644
--- a/tests/lib/test-case.vala
+++ b/tests/lib/test-case.vala
@@ -21,9 +21,17 @@
  *     Julien Peeters <contact julienpeeters fr>
  *     Simon McVittie <simon mcvittie collabora co uk>
  *
- * Copied from libgee/tests/testcase.vala.
+ * Adapted from libgee/tests/testcase.vala.
  */
 
+/**
+ * A test case for Folks, containing one or more individual tests.
+ *
+ * The constructor configures Folks to disallow all backends, via
+ * ``FOLKS_BACKENDS_ALLOWED``. Subclasses are expected to reset
+ * this variable to a suitable value in their constructors or
+ * set_up() methods.
+ */
 public abstract class Folks.TestCase : Object
 {
   private GLib.TestSuite _suite;
@@ -48,21 +56,39 @@ public abstract class Folks.TestCase : Object
             adaptor.name, adaptor.set_up, adaptor.run, adaptor.tear_down));
     }
 
-  /* Set up for one test. If you have more than one test case, this will
-   * be called once per test. */
+  /**
+   * Set up for one test. If you have more than one test, this will
+   * be called once per test.
+   *
+   * Subclasses may override this method. They are expected to chain up
+   * as the first thing in their implementation.
+   */
   public virtual void set_up ()
     {
     }
 
-  /* Clean up after one test. If you have more than one test case, this will
-   * be called once per test. It should undo set_up (). */
+  /**
+   * Clean up after one test, undoing set_up(). If you have more than
+   * one test, this will be called once per test.
+   *
+   * Subclasses may override this method. They are expected to chain up
+   * as the last thing in their implementation.
+   */
   public virtual void tear_down ()
     {
     }
 
-  /* Clean up after all tests. If you have more than one test case, this
+  /**
+   * Clean up after all tests. If you have more than one test case, this
    * will be called once, the last time only. It should undo the
-   * constructor, and must be idempotent (i.e. OK to call more than once). */
+   * constructor, and must be idempotent (i.e. OK to call more than once).
+   *
+   * Subclasses may override this method. They are expected to chain up
+   * as the last thing in their implementation.
+   *
+   * If there are no reference leaks, this method will be called
+   * automatically when the TestCase is destroyed.
+   */
   public virtual void final_tear_down ()
     {
     }
diff --git a/tests/lib/tracker/test-case.vala b/tests/lib/tracker/test-case.vala
index 1340328..20c9ac8 100644
--- a/tests/lib/tracker/test-case.vala
+++ b/tests/lib/tracker/test-case.vala
@@ -20,10 +20,31 @@
  *      Simon McVittie <simon mcvittie collabora co uk>
  */
 
+/**
+ * A test case for the Tracker backend.
+ *
+ * Folks is configured to use the Tracker backend as primary store,
+ * and no other backends.
+ *
+ * FIXME: For now, this relies on running under with-session-bus-tracker.sh
+ * with AVATAR_FILE_PATH and FOLKS_BACKEND_PATH set.
+ */
 public class TrackerTest.TestCase : Folks.TestCase
 {
+  /**
+   * The Tracker backend.
+   *
+   * The subclass is expected to have called its set_up() method at
+   * some point before tear_down() is reached.
+   */
   public TrackerTest.Backend? tracker_backend = null;
 
+  /**
+   * Set environment variables and create the tracker backend.
+   *
+   * FIXME: maybe it shouldn't be created until set_up()? (Tests
+   * will need to be checked to make sure that's OK.)
+   */
   public TestCase (string name)
     {
       base (name);