[svn-commits] russell: branch dvossel/test_api r235651 - /team/dvossel/test_api/include/ast...

[SVN commits to the Digium repositories]

Author: russell
Date: Fri Dec 18 16:35:47 2009
New Revision: 235651

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=235651
Log:
Tweak doxygen stuff a bit.

Modified:
    team/dvossel/test_api/include/asterisk/test.h

Modified: team/dvossel/test_api/include/asterisk/test.h
URL: http://svnview.digium.com/svn/asterisk/team/dvossel/test_api/include/asterisk/test.h?view=diff&rev=235651&r1=235650&r2=235651
==============================================================================
--- team/dvossel/test_api/include/asterisk/test.h (original)
+++ team/dvossel/test_api/include/asterisk/test.h Fri Dec 18 16:35:47 2009
@@ -18,8 +18,11 @@
 
 /*!
  * \file
+ * \brief Test Framework API
+ *
+ * For an overview on how to use the test API, see \ref AstUnitTestAPI
+ *
  * \author David Vossel <dvossel at digium.com>
- * \brief Test Framework API
  */
 
 #ifndef _AST_TEST_H_
@@ -30,10 +33,15 @@
 #include "asterisk/strings.h"
 #endif
 
-/*! USING THE TEST FRAMEWORK
+/*! 
 
-1. DEFINE TEST: Create a callback function for the test
-   using the AST_TEST_DEFINE macro.
+\page AstUnitTestAPI Asterisk Unit Test API
+
+\section UnitTestAPIUsage How to Use the Unit Test API
+
+\subsection DefineTest Define a Test
+
+   Create a callback function for the test using the AST_TEST_DEFINE macro.
 
    Each defined test has three arguments avaliable to it's test code.
        \param struct ast_test_info *info
@@ -45,6 +53,7 @@
 
    Below is an example of how to define and write a test function.
 
+\code
    AST_TEST_DEFINE(sample_test_cb) \\The name of the callback function
    {                                     \\The the function's body 
       switch (cmd) {
@@ -70,13 +79,16 @@
       }
       return res;                 \\ result must be of type enum ast_test_result_state
    }
+\endcode
 
    Every callback function is passed an ast_test_args object which contains
    an ast_str allowing the function to provide an optional short description of
    what went wrong if the test failed. This is done by writing to
    args->ast_test_error_str.
 
-2. REGISTER TEST: Register the test using the AST_TEST_REGISTER macro.
+\subsection RegisterTest Register a Test 
+
+   Register the test using the AST_TEST_REGISTER macro.
 
    AST_TEST_REGISTER uses the callback function to retrieve all the information
    pertaining to a test, so the callback function is the only argument required
@@ -88,14 +100,18 @@
 
    AST_TEST_UNREGISTER(sample_test_cb);  \\ Remove a registered test by callback function
 
-3. EXECUTE: Execute and generate test results via CLI commands
+\subsection ExecuteTest Execute a Test
+
+   Execute and generate test results via CLI commands
 
    CLI Examples:
+\code
    'test show registered all'  will show every registered test.
    'test execute all'          will execute every registered test.
    'test show results all'     will show detailed results for ever executed test
    'test generate results xml' will generate a test report in xml format
    'test generate results txt' will generate a test report in txt format
+\endcode
 */
 
 /*! Macros used for defining and registering a test */