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.

4 files changed, 142 insertions, 33 deletions

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
    */