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.

1 files changed, 70 insertions, 9 deletions

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),          \