Doc/cookbook.

doc/cookbook.html: removed. Replaced by cookbook.doc.

* doc/cookbook.dox: added, conversion of cookbook.html to Doxygen format.

* doc/other_documentation.dox: added groups definition.

* doc/Makefile.am: replaced cookbook.html by cookbook.dox

* doc/Doxyfile.in: added predefined CPPUNIT_HAVE_CPP_SOURCE_ANNOTATION.
Replaced cookbook.html by cookbook.dox.

* include/cppunitui/mfc/TestRunner.h: added, extracted from
include/msvc6/testrunner/TestRunner.h. Moved class TestRunner to namespace
CppUnit::MfcUi.

* include/msvc6/testrunner/TestRunner.h: deprecated. A simple typedef to
CppUnit::MfcUi::TestRunner.

* include/textui/TestRuner.h: added, extracted from
include/cppunit/TextTestRunner.h.

* src/cppunit/TextTestRunner.cpp: renamed TestRunner.cpp. Moved into
namespace CppUnit::TextUi.

* src/msvc6/testruner/TestRunner.cpp: moved into namespace CppUnit::MfcUi.

* src/cppunit/CompilerOutputter.cpp: removed printing "- " before
NotEqualException addional message, for consistency between different
TestRunner (Mfc,Text...)

* include/cppunit/Asserter.h:
* include/cppunit/CompilerOutputter.h:
* include/cppunit/Exception.h:
* include/cppunit/NotEqualException.h:
* include/cppunit/Outputter.h:
* include/cppunit/SourceLine.h:
* include/cppunit/TestAssert.h:
* include/cppunit/TestCaller.h:
* include/cppunit/TestFailure.h:
* include/cppunit/TestFixture.h:
* include/cppunit/TestListener.h:
* include/cppunit/TestResult.h:
* include/cppunit/TestResultCollector.h:
* include/cppunit/TestSucessListener.h:
* include/cppunit/TestSuite.h:
* include/cppunit/TextTestProgressListener.h:
* include/cppunit/TextTestRunner.h:
* include/cppunit/XmlOutputter.h:
* include/cppunit/extensions/AutoRegisterSuite.h:
* include/cppunit/extensions/HelperMacros.h:
* include/cppunit/extensions/TestFactoryRegistry.h:
* include/cppunit/extensions/TestSuiteBuilder.h:
* include/cppunit/extensions/TestSuiteFactory.h: doc update. organization
in groups.

* examples/msvc6/CppUnitTestApp/CppUnitTestApp.cpp:
* examples/msvc6/HostApp/HostApp.cpp: updated to use
CppUnit::MfcUi::TestRunner.

* examples/cppunittest/CppUnitTestMain.cpp: updated to use
CppUnit::TextUi::TestRunner.

25 files changed, 314 insertions, 140 deletions

diff --git a/include/cppunit/Asserter.h b/include/cppunit/Asserter.h
index 1313242..808b909 100644
--- a/include/cppunit/Asserter.h
+++ b/include/cppunit/Asserter.h
@@ -9,6 +9,7 @@ namespace CppUnit
 {
 
 /*! \brief A set of functions to help writing assertion macros.
+ * \ingroup CreatingNewAssertions
  *
  * Here is an example of assertion, a simplified version of the
  * actual assertion implemented in examples/cppunittest/XmlUniformiser.h:
@@ -49,6 +50,8 @@ namespace Asserter
   /*! Throws a Exception with the specified message and location.
    * \param shouldFail if \c true then the exception is thrown. Otherwise
    *                   nothing happen.
+   * \param message Message explaining the assertion failiure.
+   * \param sourceLine Location of the assertion.
    */
   void CPPUNIT_API failIf( bool shouldFail, 
                            std::string message, 
@@ -59,6 +62,7 @@ namespace Asserter
    * \param actual Text describing the actual value.
    * \param additionalMessage Additional message. Usually used to report
    *                          where the "difference" is located.
+   * \param sourceLine Location of the assertion.
    */
   void CPPUNIT_API failNotEqual( std::string expected, 
                                  std::string actual, 
@@ -68,6 +72,11 @@ namespace Asserter
   /*! Throws a NotEqualException with the specified message and location.
    * \param shouldFail if \c true then the exception is thrown. Otherwise
    *                   nothing happen.
+   * \param expected Text describing the expected value.
+   * \param actual Text describing the actual value.
+   * \param additionalMessage Additional message. Usually used to report
+   *                          where the "difference" is located.
+   * \param sourceLine Location of the assertion.
    */
   void CPPUNIT_API failNotEqualIf( bool shouldFail,
                                    std::string expected, 
diff --git a/include/cppunit/CompilerOutputter.h b/include/cppunit/CompilerOutputter.h
index 73176ff..0075972 100644
--- a/include/cppunit/CompilerOutputter.h
+++ b/include/cppunit/CompilerOutputter.h
@@ -16,7 +16,44 @@ class TestFailure;
 class TestResultCollector;
 
 /*! 
- * \brief Outputs test results in a compiler compatible format.
+ * \brief Outputs a TestResultCollector in a compiler compatible format.
+ * \ingroup WritingTestResult
+ *
+ * Printing the test results in a compiler compatible format (assertion
+ * location has the same format as compiler error), allow you to use your
+ * IDE to jump to the assertion failure.
+ *
+ * For example, when running the test in a post-build with VC++, if an assertion
+ * fails, you can jump to the assertion by pressing F4 (jump to next error).
+ *
+ * You should use defaultOutputter() to create an instance.
+ *
+ * Heres is an example of usage (from examples/cppunittest/CppUnitTestMain.cpp):
+ * \code
+ * int main( int argc, char* argv[] ) {
+ *   // if command line contains "-selftest" then this is the post build check
+ *   // => the output must be in the compiler error format.
+ *   bool selfTest = (argc > 1)  &&  
+ *                   (std::string("-selftest") == argv[1]);
+ *
+ *   CppUnit::TextUi::TestRunner runner;
+ *   runner.addTest( CppUnitTest::suite() );   // Add the top suite to the test runner
+ * 
+ *  if ( selfTest )
+ *   { // Change the default outputter to a compiler error format outputter
+ *     // The test runner owns the new outputter.
+ *     runner.setOutputter( CppUnit::CompilerOutputter::defaultOutputter( 
+ *                                                        &runner.result(),
+ *                                                         std::cerr ) );
+ *   }
+ * 
+ *  // Run the test and don't wait a key if post build check.
+ *   bool wasSucessful = runner.run( "", !selfTest );
+ * 
+ *   // Return error code 1 if the one of test failed.
+ *   return wasSucessful ? 0 : 1;
+ * }
+ * \endcode
  */
 class CPPUNIT_API CompilerOutputter : public Outputter
 {
@@ -29,6 +66,8 @@ public:
   /// Destructor.
   virtual ~CompilerOutputter();
 
+  /*! Creates an instance of an outputter that matches your current compiler.
+   */
   static CompilerOutputter *defaultOutputter( TestResultCollector *result,
                                               std::ostream &stream );
 
diff --git a/include/cppunit/Exception.h b/include/cppunit/Exception.h
index 2b4edb5..505d16e 100644
--- a/include/cppunit/Exception.h
+++ b/include/cppunit/Exception.h
@@ -9,6 +9,7 @@
 namespace CppUnit {
 
 /*! \brief Exceptions thrown by failed assertions.
+ * \ingroup BrowsingCollectedTestResult
  *
  * Exception is an exception that serves
  * descriptive strings through its what() method
diff --git a/include/cppunit/NotEqualException.h b/include/cppunit/NotEqualException.h
index 197f3ce..52cc7d2 100644
--- a/include/cppunit/NotEqualException.h
+++ b/include/cppunit/NotEqualException.h
@@ -7,6 +7,7 @@
 namespace CppUnit {
 
 /*! \brief Exception thrown by failed equality assertions.
+ * \ingroup BrowsingCollectedTestResult
  */
 class CPPUNIT_API NotEqualException : public Exception
 {
diff --git a/include/cppunit/Outputter.h b/include/cppunit/Outputter.h
index 1805dc9..1f28652 100644
--- a/include/cppunit/Outputter.h
+++ b/include/cppunit/Outputter.h
@@ -8,6 +8,7 @@ namespace CppUnit
 {
 
 /*! \brief Abstract outputter to print test result summary.
+ * \ingroup WritingTestResult
  */
 class CPPUNIT_API Outputter
 {
diff --git a/include/cppunit/SourceLine.h b/include/cppunit/SourceLine.h
index 4ef423a..5d2a3c1 100644
--- a/include/cppunit/SourceLine.h
+++ b/include/cppunit/SourceLine.h
@@ -4,7 +4,9 @@
 #include <cppunit/Portability.h>
 #include <string>
 
-/*! Constructs a SourceLine object initialized with the location where the macro is expanded.
+/*! \brief Constructs a SourceLine object initialized with the location where the macro is expanded.
+ * \ingroup CreatingNewAssertions
+ * \relates CppUnit::SourceLine
  * Used to write your own assertion macros.
  * \see Asserter for example of usage.
  */
@@ -14,11 +16,14 @@
 namespace CppUnit
 {
 
-/*! \class SourceLine
- * \brief This class represents the location of a line of text in a specified file.
- * Use the CPPUNIT_SOURCELINE macro to construct that object.
+/*! \brief Represents a source line location.
+ * \ingroup CreatingNewAssertions
+ * \ingroup BrowsingCollectedTestResult
  *
  * Used to capture the failure location in assertion.
+ * 
+ * Use the CPPUNIT_SOURCELINE() macro to construct that object. Typically used when
+ * writing an assertion macro in association with Asserter.
  *
  * \see Asserter.
  */
diff --git a/include/cppunit/Test.h b/include/cppunit/Test.h
index 98f1764..2ee2a48 100644
--- a/include/cppunit/Test.h
+++ b/include/cppunit/Test.h
@@ -9,6 +9,7 @@ namespace CppUnit {
 class TestResult;
 
 /*! \brief Base class for all test objects.
+ * \ingroup BrowsingCollectedTestResult
  *
  * All test objects should be a subclass of Test.  Some test objects,
  * TestCase for example, represent one individual test.  Other test
diff --git a/include/cppunit/TestAssert.h b/include/cppunit/TestAssert.h
index 46071ee..9cbdf44 100644
--- a/include/cppunit/TestAssert.h
+++ b/include/cppunit/TestAssert.h
@@ -8,6 +8,29 @@
 
 namespace CppUnit {
 
+  /*! \brief Traits used by CPPUNIT_ASSERT_EQUAL().
+   *
+   * Here is an example of specialization of that traits:
+   *
+   * \code
+   * template<>
+   * struct assertion_traits<std::string>   // specialization for the std::string type
+   * {
+   *   static bool equal( const std::string& x, const std::string& y )
+   *   {
+   *     return x == y;
+   *   }
+   * 
+   *   static std::string toString( const std::string& x )
+   *   {
+   *     std::string text = '"' + x + '"';    // adds quote around the string to see whitespace
+   *     OStringStream ost;
+   *     ost << text;
+   *     return ost.str();
+   *   }
+   * };
+   * \endcode
+   */
   template <class T>
   struct assertion_traits 
   {  
@@ -86,24 +109,28 @@ namespace CppUnit {
   }
 
 
-/** A set of macros which allow us to get the line number
+/* A set of macros which allow us to get the line number
  * and file name at the point of an error.
  * Just goes to show that preprocessors do have some
  * redeeming qualities.
  */
 #if CPPUNIT_HAVE_CPP_SOURCE_ANNOTATION
-#  define CPPUNIT_ASSERT(condition)                        \
+/** Assertions that a condition is \c true.
+ * \ingroup Assertions
+ */
+#define CPPUNIT_ASSERT(condition)                          \
   ( ::CppUnit::Asserter::failIf( !(condition),             \
                                  (#condition),             \
                                  CPPUNIT_SOURCELINE() ) )
 #else
-#  define CPPUNIT_ASSERT(condition)                        \
+#define CPPUNIT_ASSERT(condition)                          \
   ( ::CppUnit::Asserter::failIf( !(condition),             \
                                  "",                       \
                                  CPPUNIT_SOURCELINE() ) )
 #endif
 
 /** Assertion with a user specified message.
+ * \ingroup Assertions
  * \param message Message reported in diagnostic if \a condition evaluates
  *                to \c false.
  * \param condition If this condition evaluates to \c false then the
@@ -114,7 +141,8 @@ namespace CppUnit {
                                  (message),                \
                                  CPPUNIT_SOURCELINE() ) )
 
-/** Failure with a user specified message.
+/** Fails with the specified message.
+ * \ingroup Assertions
  * \param message Message reported in diagnostic.
  */
 #define CPPUNIT_FAIL( message )                            \
@@ -123,19 +151,50 @@ namespace CppUnit {
 
 #ifdef CPPUNIT_ENABLE_SOURCELINE_DEPRECATED
 /// Generalized macro for primitive value comparisons
-/** Equality and string representation can be defined with
- * an appropriate assertion_traits class.
- * A diagnostic is printed if actual and expected values disagree.
- */
 #define CPPUNIT_ASSERT_EQUAL(expected,actual)                    \
   ( ::CppUnit::TestAssert::assertEquals( (expected),             \
                                          (actual),               \
                                          __LINE__, __FILE__ ) )
 #else
+/** Asserts that two values are equals.
+ * \ingroup Assertions
+ *
+ * Equality and string representation can be defined with
+ * an appropriate CppUnit::assertion_traits class.
+ *
+ * A diagnostic is printed if actual and expected values disagree.
+ *
+ * Requirement for \a expected and \a actual parameters:
+ * - They are exactly of the same type
+ * - They are serializable into a std::strstream using operator <<.
+ * - They can be compared using operator ==. 
+ *
+ * The last two requirements (serialization and comparison) can be
+ * removed by specializing the CppUnit::assertion_traits.
+ */
 #define CPPUNIT_ASSERT_EQUAL(expected,actual)                     \
   ( ::CppUnit::TestAssert::assertEquals( (expected),              \
                                          (actual),                \
                                          CPPUNIT_SOURCELINE() ) )
+
+/** Asserts that two values are equals, provides additional messafe on failure.
+ * \ingroup Assertions
+ *
+ * Equality and string representation can be defined with
+ * an appropriate assertion_traits class.
+ *
+ * A diagnostic is printed if actual and expected values disagree.
+ * The message is printed in addition to the expected and actual value
+ * to provide additional information.
+ *
+ * Requirement for \a expected and \a actual parameters:
+ * - They are exactly of the same type
+ * - They are serializable into a std::strstream using operator <<.
+ * - They can be compared using operator ==. 
+ *
+ * The last two requirements (serialization and comparison) can be
+ * removed by specializing the CppUnit::assertion_traits.
+ */
 #define CPPUNIT_ASSERT_EQUAL_MESSAGE(expected,actual,message)     \
   ( ::CppUnit::TestAssert::assertEquals( (expected),              \
                                          (actual),                \
@@ -143,7 +202,9 @@ namespace CppUnit {
                                          (message) ) )
 #endif
 
-/// Macro for primitive value comparisons
+/*! \brief Macro for primitive value comparisons
+ * \ingroup Assertions
+ */
 #define CPPUNIT_ASSERT_DOUBLES_EQUAL(expected,actual,delta)       \
   ( ::CppUnit::TestAssert::assertDoubleEquals( (expected),        \
                                                (actual),          \
diff --git a/include/cppunit/TestCaller.h b/include/cppunit/TestCaller.h
index 85c12d0..7853019 100644
--- a/include/cppunit/TestCaller.h
+++ b/include/cppunit/TestCaller.h
@@ -12,16 +12,21 @@
 
 namespace CppUnit {
 
-//! \internal
+/*! \brief Marker class indicating that no exception is expected by TestCaller.
+ * This class is an implementation detail. You should never use this class directly.
+ */
 class CPPUNIT_API NoExceptionExpected
 {
 private:
-    // Nobody must be able to construct an exception of this type.
-    NoExceptionExpected();
+  //! Prevent class instantiation.
+  NoExceptionExpected();
 };
 
 
-//! \internal
+/*! \brief (Implementation) Traits used by TestCaller to expect an exception.
+ *
+ * This class is an implementation detail. You should never use this class directly.
+ */
 template<typename ExceptionType>
 struct ExpectedExceptionTraits
 {
@@ -39,6 +44,11 @@ struct ExpectedExceptionTraits
 };
 
 
+/*! \brief (Implementation) Traits specialization used by TestCaller to 
+ * expect no exception.
+ *
+ * This class is an implementation detail. You should never use this class directly.
+ */
 template<>
 struct ExpectedExceptionTraits<NoExceptionExpected>
 {
@@ -53,6 +63,7 @@ struct ExpectedExceptionTraits<NoExceptionExpected>
 
 
 /*! \brief Generate a test case from a fixture method.
+ * \ingroup WritingTestFixture
  *
  * A test caller provides access to a test case method 
  * on a test fixture class.  Test callers are useful when 
diff --git a/include/cppunit/TestFailure.h b/include/cppunit/TestFailure.h
index b1e1d8f..a610072 100644
--- a/include/cppunit/TestFailure.h
+++ b/include/cppunit/TestFailure.h
@@ -11,7 +11,8 @@ class SourceLine;
 class Test;
 
 
-/*! \brief Record of a failed test execution.
+/*! \brief Record of a failed Test execution.
+ * \ingroup BrowsingCollectedTestResult
  *
  * A TestFailure collects a failed test together with
  * the caught exception.
diff --git a/include/cppunit/TestFixture.h b/include/cppunit/TestFixture.h
index 309df2c..eb2264b 100644
--- a/include/cppunit/TestFixture.h
+++ b/include/cppunit/TestFixture.h
@@ -7,6 +7,7 @@ namespace CppUnit {
 
 
 /*! \brief Wraps a test case with setUp and tearDown methods.
+ * \ingroup WritingTestFixture
  *
  * A TestFixture is used to provide a common environment for a set
  * of test cases.
@@ -25,7 +26,7 @@ namespace CppUnit {
  * \code
  * class MathTest : public CppUnit::TestFixture {
  * protected:
- *   int m_value1;
+ *   int m_value1, m_value2;
  *
  * public:
  *   MathTest() {}
diff --git a/include/cppunit/TestListener.h b/include/cppunit/TestListener.h
index a9bca1c..595bcb7 100644
--- a/include/cppunit/TestListener.h
+++ b/include/cppunit/TestListener.h
@@ -12,6 +12,7 @@ class TestFailure;
 
 
 /*! \brief Listener for test progress and result.
+ * \ingroup TrackingTestExecution
  *
  * Implementing the Observer pattern a TestListener may be registered
  * to a TestResult to obtain information on the testing progress. Use
diff --git a/include/cppunit/TestResult.h b/include/cppunit/TestResult.h
index 5351436..b573cf3 100644
--- a/include/cppunit/TestResult.h
+++ b/include/cppunit/TestResult.h
@@ -23,9 +23,10 @@ class TestListener;
 #endif
 
 /*! \brief Manages TestListener.
+ * \ingroup TrackingTestExecution
  *
  * A single instance of this class is used when running the test. It is usually
- * created by the test runner (TextTestRunner).
+ * created by the test runner (TestRunner).
  *
  * This class shouldn't have to be inherited from. Use a TestListener
  * or one of its subclasses to be informed of the ongoing tests.
diff --git a/include/cppunit/TestResultCollector.h b/include/cppunit/TestResultCollector.h
index c40282c..a9cbcfe 100644
--- a/include/cppunit/TestResultCollector.h
+++ b/include/cppunit/TestResultCollector.h
@@ -23,6 +23,9 @@ namespace CppUnit
 
 
 /*! \brief Collects test result.
+ * \ingroup WritingTestResult
+ * \ingroup BrowsingCollectedTestResult
+ * 
  * A TestResultCollector is a TestListener which collects the results of executing 
  * a test case. It is an instance of the Collecting Parameter pattern.
  *
diff --git a/include/cppunit/TestSucessListener.h b/include/cppunit/TestSucessListener.h
index 410049f..51dc248 100644
--- a/include/cppunit/TestSucessListener.h
+++ b/include/cppunit/TestSucessListener.h
@@ -9,6 +9,7 @@ namespace CppUnit
 {
 
 /*! \brief TestListener that checks if any test case failed.
+ * \ingroup TrackingTestExecution
  */
 class CPPUNIT_API TestSucessListener : public TestListener,
                                        public SynchronizedObject
diff --git a/include/cppunit/TestSuite.h b/include/cppunit/TestSuite.h
index 031f597..3cd77cb 100644
--- a/include/cppunit/TestSuite.h
+++ b/include/cppunit/TestSuite.h
@@ -22,6 +22,7 @@ class TestResult;
 
 
 /*! \brief A Composite of Tests.
+ * \ingroup CreatingTestSuite
  *
  * It runs a collection of test cases. Here is an example.
  * \code
diff --git a/include/cppunit/TextOutputter.h b/include/cppunit/TextOutputter.h
index 2ebffe2..db09575 100644
--- a/include/cppunit/TextOutputter.h
+++ b/include/cppunit/TextOutputter.h
@@ -15,6 +15,7 @@ class TestFailure;
 
 
 /*! \brief Prints a TestResultCollector to a text stream.
+ * \ingroup WritingTestResult
  */
 class CPPUNIT_API TextOutputter : public Outputter
 {
diff --git a/include/cppunit/TextTestProgressListener.h b/include/cppunit/TextTestProgressListener.h
index 6a5775f..dbd22cb 100644
--- a/include/cppunit/TextTestProgressListener.h
+++ b/include/cppunit/TextTestProgressListener.h
@@ -9,6 +9,7 @@ namespace CppUnit
 
 /*! 
  * \brief TestListener that show the status of each TestCase test result.
+ * \ingroup TrackingTestExecution
  */
 class CPPUNIT_API TextTestProgressListener : public TestListener
 {
diff --git a/include/cppunit/TextTestResult.h b/include/cppunit/TextTestResult.h
index 4e355bc..0e39376 100644
--- a/include/cppunit/TextTestResult.h
+++ b/include/cppunit/TextTestResult.h
@@ -12,8 +12,9 @@ class Exception;
 class Test;
 
 /*! \brief Holds printable test result (DEPRECATED).
+ * \ingroup TrackingTestExecution
  * 
- * Use class TextTestProgressListener and TextOutputter instead.
+ * deprecated Use class TextTestProgressListener and TextOutputter instead.
  */
 class CPPUNIT_API TextTestResult : public TestResult,
                                    public TestResultCollector
diff --git a/include/cppunit/TextTestRunner.h b/include/cppunit/TextTestRunner.h
index 0d7a138..f7c5fa0 100644
--- a/include/cppunit/TextTestRunner.h
+++ b/include/cppunit/TextTestRunner.h
@@ -1,93 +1,16 @@
 #ifndef CPPUNIT_TEXTTESTRUNNER_H
 #define CPPUNIT_TEXTTESTRUNNER_H
 
-#include <string>
-#include <vector>
+#include <cppunitui/text/TestRunner.h>
 
 namespace CppUnit {
 
-class Outputter;
-class Test;
-class TestSuite;
-class TextOutputter;
-class TestResult;
-class TestResultCollector;
-
 /*!
  * \brief A text mode test runner.
- *
- * The test runner manage the life cycle of the added tests.
- *
- * The test runner can run only one of the added tests or all the tests. 
- *
- * TextTestRunner prints out a trace as the tests are executed followed by a
- * summary at the end. The trace and summary print are optional.
- *
- * Here is an example of use:
- *
- * \code
- * CppUnit::TextTestRunner runner;
- * runner.addTest( ExampleTestCase::suite() );
- * runner.run( "", true );    // Run all tests and wait
- * \endcode
- *
- * The trace is printed using a TextTestProgressListener. The summary is printed
- * using a TextOutputter. 
- *
- * You can specify an alternate Outputter at construction
- * or later with setOutputter(). 
- *
- * After construction, you can register additional TestListener to eventManager(),
- * for a custom progress trace, for example.
- *
- * \code
- * CppUnit::TextTestRunner runner;
- * runner.addTest( ExampleTestCase::suite() );
- * runner.setOutputter( CppUnit::CompilerOutputter::defaultOutputter( 
- *                          &runner.result(),
- *                          std::cerr ) );
- * MyCustomProgressTestListener progress;
- * runner.eventManager().addListener( &progress );
- * runner.run( "", true );    // Run all tests and wait
- * \endcode
- *
- * \see CompilerOutputter, XmlOutputter, TextOutputter.
+ * \ingroup ExecutingTest
+ * \deprecated Use CppUnit::TextUi::TestRunner instead.
  */
-class CPPUNIT_API TextTestRunner
-{
-public:
-  TextTestRunner( Outputter *outputter =NULL );
-
-  virtual ~TextTestRunner();
-
-  bool run( std::string testName ="",
-            bool wait = false,
-            bool printResult = true,
-            bool printProgress = true );
-
-  void addTest( Test *test );
-
-  void setOutputter( Outputter *outputter );
-
-  TestResultCollector &result() const;
-
-  TestResult &eventManager() const;
-
-protected:
-  virtual bool runTest( Test *test,
-                        bool printTextProgress );
-  virtual bool runTestByName( std::string testName,
-                              bool printProgress );
-  virtual void wait( bool doWait );
-  virtual void printResult( bool doPrintResult );
-
-  virtual Test *findTestByName( std::string name ) const;
-
-  TestSuite *m_suite;
-  TestResultCollector *m_result;
-  TestResult *m_eventManager;
-  Outputter *m_outputter;
-};
+typedef CppUnit::TextUi::TestRunner TextTestRunner;
 
 }  // namespace CppUnit
 
diff --git a/include/cppunit/XmlOutputter.h b/include/cppunit/XmlOutputter.h
index 45e824e..80fbcee 100644
--- a/include/cppunit/XmlOutputter.h
+++ b/include/cppunit/XmlOutputter.h
@@ -25,11 +25,15 @@ class TestResultCollector;
 
 
 /*! \brief Outputs a TestResultCollector in XML format.
+ * \ingroup WritingTestResult
  */
 class CPPUNIT_API XmlOutputter : public Outputter
 {
 public:
   /*! Constructs a XmlOutputter object.
+   * \param result Result of the test run.
+   * \param stream Stream used to output the XML output.
+   * \param encoding Encoding used in the XML file (default is Latin-1). 
    */
   XmlOutputter( TestResultCollector *result,
                 std::ostream &stream,
@@ -38,13 +42,10 @@ public:
   /// Destructor.
   virtual ~XmlOutputter();
 
-  /*! Writes the specified result as an XML document in the specified stream.
+  /*! Writes the specified result as an XML document to the stream.
    *
    * Refer to examples/cppunittest/XmlOutputterTest.cpp for example
    * of use and XML document structure.
-   *
-   * \param result TestResult to write.
-   * \param stream Output stream the result are wrote into.
    */
   virtual void write();
 
diff --git a/include/cppunit/extensions/AutoRegisterSuite.h b/include/cppunit/extensions/AutoRegisterSuite.h
index 28a3e7c..8af3489 100644
--- a/include/cppunit/extensions/AutoRegisterSuite.h
+++ b/include/cppunit/extensions/AutoRegisterSuite.h
@@ -9,13 +9,19 @@ namespace CppUnit {
 
   /** Automatically register the test suite of the specified type.
    *
+   * You should not use this class directly. Instead, use the following macros:
+   * - CPPUNIT_TEST_SUITE_REGISTRATION()
+   * - CPPUNIT_TEST_SUITE_NAMED_REGISTRATION()
+   *
    * This object will register the test returned by TestCaseType::suite()
    * when constructed to the test registry.
    *
    * This object is intented to be used as a static variable.
    *
+   *
    * \param TestCaseType Type of the test case which suite is registered.
-   * \see CPPUNIT_TEST_SUITE_REGISTRATION, CppUnit::TestFactoryRegistry.
+   * \see CPPUNIT_TEST_SUITE_REGISTRATION, CPPUNIT_TEST_SUITE_NAMED_REGISTRATION
+   * \see CppUnit::TestFactoryRegistry.
    */
   template<typename TestCaseType>
   class AutoRegisterSuite
diff --git a/include/cppunit/extensions/HelperMacros.h b/include/cppunit/extensions/HelperMacros.h
index a5415fe..142cd1d 100644
--- a/include/cppunit/extensions/HelperMacros.h
+++ b/include/cppunit/extensions/HelperMacros.h
@@ -15,9 +15,12 @@ namespace CppUnit
 {
   class TestFixture;
 
+  /*! \brief Abstract TestFixture factory.
+   */
   class TestFixtureFactory
   {
   public:
+    //! Creates a new TestFixture instance.
     virtual CppUnit::TestFixture *makeFixture() =0;
   };
 } // namespace CppUnit
@@ -37,6 +40,12 @@ namespace CppUnit
 #endif
 
 
+/*! \addtogroup WritingTestFixture Writing test fixture
+ */
+/** @{
+ */
+
+
 /** \file
  * Macros intended to ease the definition of test suites.
  *
@@ -47,7 +56,7 @@ namespace CppUnit
  *
  * \code
  * #include <cppunit/extensions/HelperMacros.h>
- * class MyTest : public CppUnit::TestCase {
+ * class MyTest : public CppUnit::TestFixture {
  *   CPPUNIT_TEST_SUITE( MyTest );
  *   CPPUNIT_TEST( testEquality );
  *   CPPUNIT_TEST( testSetName );
@@ -83,7 +92,7 @@ namespace CppUnit
  *
  * \code
  * template<typename CharType>
- * class StringTest : public CppUnit::Testcase {
+ * class StringTest : public CppUnit::TestFixture {
  *   CPPUNIT_TEST_SUITE( StringTest );
  *   CPPUNIT_TEST( testAppend );
  *   CPPUNIT_TEST_SUITE_END();
@@ -101,13 +110,14 @@ namespace CppUnit
  */
 
 
-/** Begin test suite
+/*! \brief Begin test suite
  *
  * This macro starts the declaration of a new test suite.
  * Use CPPUNIT_TEST_SUB_SUITE() instead, if you wish to include the
  * test suite of the parent class.
  *
- * \param ATestFixtureType Type of the test case class.
+ * \param ATestFixtureType Type of the test case class. This type \b MUST
+ *                         be derived from TestFixture.
  * \see CPPUNIT_TEST_SUB_SUITE, CPPUNIT_TEST, CPPUNIT_TEST_SUITE_END, 
  * \see CPPUNIT_TEST_SUITE_REGISTRATION, CPPUNIT_TEST_EXCEPTION, CPPUNIT_TEST_FAIL.
  */
@@ -129,7 +139,7 @@ namespace CppUnit
       CppUnit::TestSuiteBuilder<__ThisTestFixtureType> builder( suite );
 
 
-/** Begin test suite (includes parent suite)
+/*! \brief Begin test suite (includes parent suite)
  * 
  * This macro may only be used in a class whose parent class
  * defines a test suite using CPPUNIT_TEST_SUITE() or CPPUNIT_TEST_SUB_SUITE().
@@ -154,7 +164,8 @@ namespace CppUnit
  * };
  * \endcode
  *
- * \param ATestFixtureType Type of the test case class.
+ * \param ATestFixtureType Type of the test case class. This type \b MUST
+ *                         be derived from TestFixture.
  * \param ASuperClass   Type of the parent class.
  * \see CPPUNIT_TEST_SUITE.
  */
@@ -165,7 +176,7 @@ namespace CppUnit
       __ThisSuperClassType::registerTests( suite, factory )
 
 
-/** Add a method to the suite.
+/*! \brief Add a method to the suite.
  * \param testMethod Name of the method of the test case to add to the
  *                   suite. The signature of the method must be of
  *                   type: void testMethod();
@@ -177,13 +188,13 @@ namespace CppUnit
                              (__ThisTestFixtureType*)factory->makeFixture() ) 
 
 
-/*!  Add a test which fail if the specified exception is not caught.
+/*! \brief Add a test which fail if the specified exception is not caught.
  *
  * Example:
  * \code
  * #include <cppunit/extensions/HelperMacros.h>
  * #include <vector>
- * class MyTest : public CppUnit::TestCase {
+ * class MyTest : public CppUnit::TestFixture {
  *   CPPUNIT_TEST_SUITE( MyTest );
  *   CPPUNIT_TEST_EXCEPTION( testVectorAtThrow, std::invalid_argument );
  *   CPPUNIT_TEST_SUITE_END();
@@ -206,15 +217,25 @@ namespace CppUnit
                              (__ThisTestFixtureType*)factory->makeFixture(),  \
                              (ExceptionType *)NULL ); 
 
-/*! Add a test which is excepted to fail.
+/*! \brief Adds a test case which is excepted to fail.
  *
- * To use when writing test case for testing utility class.
+ * The added test case expect an assertion to fail. You usually used that type
+ * of test case when testing custom assertion macros.
  *
+ * \code
+ * CPPUNIT_TEST_FAIL( testAssertFalseFail );
+ * 
+ * void testAssertFalseFail()
+ * {
+ *   CPPUNIT_ASSERT( false );
+ * }
+ * \endcode
+ * \see CreatingNewAssertions.
  */
 #define CPPUNIT_TEST_FAIL( testMethod ) \
               CPPUNIT_TEST_EXCEPTION( testMethod, CppUnit::Exception )
 
-/** End declaration of the test suite.
+/*! \brief End declaration of the test suite.
  *
  * After this macro, member access is set to "private".
  *
@@ -235,6 +256,9 @@ namespace CppUnit
   private: /* dummy typedef so that the macro can still end with ';'*/    \
     typedef ThisTestFixtureFactory __ThisTestFixtureFactory                   
 
+/** @}
+ */
+
 #define __CPPUNIT_CONCATENATE_DIRECT( s1, s2 ) s1##s2
 #define __CPPUNIT_CONCATENATE( s1, s2 ) __CPPUNIT_CONCATENATE_DIRECT( s1, s2 )
 
@@ -244,7 +268,8 @@ namespace CppUnit
 #define __CPPUNIT_MAKE_UNIQUE_NAME( str ) __CPPUNIT_CONCATENATE( str, __LINE__ )
 
 
-/** Register test suite into global registry.
+/** Adds the specified fixture suite to the unnamed registry.
+ * \ingroup CreatingTestSuite
  *
  * This macro declares a static variable whose construction
  * causes a test suite factory to be inserted in a global registry
@@ -254,28 +279,49 @@ namespace CppUnit
  * \param ATestFixtureType Type of the test case class.
  * \warning This macro should be used only once per line of code (the line
  *          number is used to name a hidden static variable).
- * \see  CPPUNIT_TEST_SUITE, CppUnit::AutoRegisterSuite, 
- *       CppUnit::TestFactoryRegistry.
+ * \see CPPUNIT_TEST_SUITE_NAMED_REGISTRATION
+ * \see CPPUNIT_TEST_SUITE, CppUnit::AutoRegisterSuite, 
+ *      CppUnit::TestFactoryRegistry.
  */
 #define CPPUNIT_TEST_SUITE_REGISTRATION( ATestFixtureType )      \
   static CppUnit::AutoRegisterSuite< ATestFixtureType >          \
              __CPPUNIT_MAKE_UNIQUE_NAME(__autoRegisterSuite )
 
 
-/** Register test suite into the specified global registry suite.
+/** Adds the specified fixture suite to the specified registry suite.
+ * \ingroup CreatingTestSuite
  *
  * This macro declares a static variable whose construction
  * causes a test suite factory to be inserted in the global registry
  * suite of the specified name. The registry is available by calling
  * the static function CppUnit::TestFactoryRegistry::getRegistry().
  * 
+ * For the suite name, use a string returned by a static function rather
+ * than a hardcoded string. That way, you can know what are the name of
+ * named registry and you don't risk mistyping the registry name.
+ *
+ * \code
+ * // MySuites.h
+ * namespace MySuites {
+ *   std::string math() { 
+ *     return "Math";
+ *   }
+ * }
+ *
+ * // ComplexNumberTest.cpp
+ * #include "MySuites.h"
+ * 
+ * CPPUNIT_TEST_SUITE_NAMED_REGISTRATION( ComplexNumberTest, MySuites::math() );
+ * \endcode
+ *
  * \param ATestFixtureType Type of the test case class.
  * \param suiteName Name of the global registry suite the test suite is 
  *                  registered into.
  * \warning This macro should be used only once per line of code (the line
  *          number is used to name a hidden static variable).
- * \see  CPPUNIT_TEST_SUITE, CppUnit::AutoRegisterSuite, 
- *       CppUnit::TestFactoryRegistry..
+ * \see CPPUNIT_TEST_SUITE_REGISTRATION
+ * \see CPPUNIT_TEST_SUITE, CppUnit::AutoRegisterSuite, 
+ *      CppUnit::TestFactoryRegistry..
  */
 #define CPPUNIT_TEST_SUITE_NAMED_REGISTRATION( ATestFixtureType, suiteName ) \
   static CppUnit::AutoRegisterSuite< ATestFixtureType >                      \
diff --git a/include/cppunit/extensions/TestFactoryRegistry.h b/include/cppunit/extensions/TestFactoryRegistry.h
index 3d715a1..6553fe5 100644
--- a/include/cppunit/extensions/TestFactoryRegistry.h
+++ b/include/cppunit/extensions/TestFactoryRegistry.h
@@ -21,50 +21,106 @@ class TestSuite;
 #endif
 
 
-/*! \brief Registry for test factory.
+/*! \brief Registry for TestFactory.
+ * \ingroup CreatingTestSuite
  *
  * Notes that the registry assumes lifetime control for any registered test.
+ *
+ * To register tests, use the macros:
+ * - CPPUNIT_TEST_SUITE_REGISTRATION(): to add tests in the unnamed registry.
+ * - CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(): to add tests in a named registry.
+ *
+ * Example 1: retreiving a suite that contains all the test registered with
+ * CPPUNIT_TEST_SUITE_REGISTRATION().
+ * \code
+ * CppUnit::TestFactoryRegistry &registry = CppUnit::TestFactoryRegistry::getRegistry();
+ * CppUnit::TestSuite *suite = registry.makeTest();
+ * \endcode
+ *
+ * Example 2: retreiving a suite that contains all the test registered with
+ * \link CPPUNIT_TEST_SUITE_NAMED_REGISTRATION() CPPUNIT_TEST_SUITE_NAMED_REGISTRATION( ..., "Math" )\endlink.
+ * \code
+ * CppUnit::TestFactoryRegistry &mathRegistry = CppUnit::TestFactoryRegistry::getRegistry( "Math" );
+ * CppUnit::TestSuite *mathSuite = mathRegistry.makeTest();
+ * \endcode
+ *
+ * Example 3: creating a test suite hierarchy composed of unnamed registration and
+ * named registration:
+ * - All Tests
+ *   - tests registered with CPPUNIT_TEST_SUITE_NAMED_REGISTRATION( ..., "Graph" )
+ *   - tests registered with CPPUNIT_TEST_SUITE_NAMED_REGISTRATION( ..., "Math" )
+ *   - tests registered with CPPUNIT_TEST_SUITE_REGISTRATION
+ *
+ * \code
+ * CppUnit::TestSuite *rootSuite = new CppUnit::TestSuite( "All tests" );
+ * rootSuite->addTest( CppUnit::TestFactoryRegistry::getRegistry( "Graph" ).makeTest() );
+ * rootSuite->addTest( CppUnit::TestFactoryRegistry::getRegistry( "Math" ).makeTest() );
+ * CppUnit::TestFactoryRegistry::getRegistry().addTestToSuite( rootSuite );
+ * \endcode
+ *
+ * The same result can be obtained with:
+ * \code
+ * CppUnit::TestFactoryRegistry &registry = CppUnit::TestFactoryRegistry::getRegistry();
+ * registry.registerFactory( CppUnit::TestFactoryRegistry::getRegistry( "Graph" ) );
+ * registry.registerFactory( CppUnit::TestFactoryRegistry::getRegistry( "Math" ) );
+ * CppUnit::TestSuite *suite = registry.makeTest();
+ * \endcode
+ *
+ * Since a TestFactoryRegistry is a TestFactory, the named registries can be 
+ * registered in the unnamed registry, creating the hierarchy links.
+ *
+ * \see TestSuiteFactory, AutoRegisterSuite
+ * \see CPPUNIT_TEST_SUITE_REGISTRATION, CPPUNIT_TEST_SUITE_NAMED_REGISTRATION
  */
 class CPPUNIT_API TestFactoryRegistry : public TestFactory
 {
 public:
   /** Constructs the registry with the specified name.
-   * \param name Name of the registry.
+   * \param name Name of the registry. It is the name of TestSuite returned by
+   *             makeTest().
    */
   TestFactoryRegistry( std::string name = "All Tests" );
 
   /// Destructor.
   virtual ~TestFactoryRegistry();
 
-  /** Makes a suite containing all the registered test.
-   * \return A new suite containing all the registered test.
+  /** Returns a new TestSuite that contains the registered test.
+   * \return A new TestSuite which contains all the test added using 
+   * registerFactory(TestFactory *).
    */
   virtual Test *makeTest();
 
-  /** Returns the registry.
-   * \return Registry.
+  /** Returns unnamed the registry.
+   * TestSuite registered using CPPUNIT_TEST_SUITE_REGISTRATION() are registered 
+   * in this registry.
+   * \return Registry which name is "All Tests".
    */
   static TestFactoryRegistry &getRegistry();
 
   /** Returns a named registry.
+   * TestSuite registered using CPPUNIT_TEST_SUITE_NAMED_REGISTRATION() are registered
+   * in the registry of the same name.
    * \param name Name of the registry to return.
-   * \return Registry. If the registry does not exist, it is created.
+   * \return Registry. If the registry does not exist, it is created with the
+   *         specified name.
    */
   static TestFactoryRegistry &getRegistry( const std::string &name );
 
-  /** Adds the registered test to the specified suite.
-   * \param suite Suite the test are added to.
+  /** Adds the registered tests to the specified suite.
+   * \param suite Suite the tests are added to.
    */
   void addTestToSuite( TestSuite *suite );
 
-  /** Registers a test factory with the specified name.
+  /** Adds the specified TestFactory with a specific name (DEPRECATED).
    * \param name Name associated to the factory.
    * \param factory Factory to register. 
+   * \deprecated Use registerFactory( TestFactory *) instead.
    */
   void registerFactory( const std::string &name,
                         TestFactory *factory );
 
-  /** Registers a test factory using its class name.
+  /** Adds the specified TestFactory to the registry.
+   *
    * \param factory Factory to register. 
    */
   void registerFactory( TestFactory *factory );
diff --git a/include/cppunit/extensions/TestSuiteBuilder.h b/include/cppunit/extensions/TestSuiteBuilder.h
index 44ad3fc..1f3e028 100644
--- a/include/cppunit/extensions/TestSuiteBuilder.h
+++ b/include/cppunit/extensions/TestSuiteBuilder.h
@@ -12,10 +12,11 @@
 
 namespace CppUnit {
 
-  /*! \brief Helper to add test to a TestSuite.
+  /*! \brief Helper to add tests to a TestSuite.
+   * \ingroup WritingTestFixture
    *
-   * All test added to the TestSuite are prefixed by TestSuite name. The resulting
-   * Test name has the following pattern:
+   * All tests added to the TestSuite are prefixed by TestSuite name. The resulting
+   * TestCase name has the following pattern:
    *
    * MyTestSuiteName.myTestName
    */