--- a/src/core/test.h	Wed Sep 06 13:34:58 2006 +0200
+++ b/src/core/test.h	Wed Sep 06 13:35:23 2006 +0200
@@ -35,30 +35,57 @@
 
 /**
  * \brief base class for new regressions tests
+ *
+ * To add a new regression test, you need to:
+ *    - create subclass of this abstract base class
+ *    - instantiate once this subclass through a static
+ *      variable.
+ *
+ * The following sample code shows you how to do this:
+ * \include samples/main-test.cc
  */
 class Test {
 public:
+	/**
+	 * \param name the name of the test
+	 */
     Test (char const *name);
     virtual ~Test ();
 
+	/**
+	 * \returns true if the test was successful, false otherwise.
+	 */
     virtual bool runTests (void) = 0;
 
 protected:
+	/**
+	 * \returns an output stream which base classes can write to
+	 *          to return extra information on test errors.
+	 */
     std::ostream &failure (void);
 };
 
 /**
- * 
+ * \brief gather and run all regression tests
  */
 class TestManager {
 public:
+	/**
+	 * Enable verbose output. If you do not enable verbose output,
+	 * nothing is printed on screen during the test runs.
+	 */
     static void enableVerbose (void);
+	/**
+	 * \returns true if all tests passed, false otherwise.
+	 *
+	 * run all registered regression tests
+	 */
     static bool runTests (void);
 
-    // helper methods
+private:
+	friend class Test;
     static void add (Test *test, char const *name);
     static std::ostream &failure (void);
-private:
     static TestManager *get (void);
     bool realRunTests (void);