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

[SVN commits to the Digium repositories]

Author: dvossel
Date: Wed Dec 16 19:21:50 2009
New Revision: 235404

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=235404
Log:
fixes documentation structure

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=235404&r1=235403&r2=235404
==============================================================================
--- team/dvossel/test_api/include/asterisk/test.h (original)
+++ team/dvossel/test_api/include/asterisk/test.h Wed Dec 16 19:21:50 2009
@@ -47,62 +47,63 @@
 
    AST_TEST_DEFINE(sample_test_cb, \\The first argument is the name of the callback function
    {                               \\The second argument is the function's body *
-       switch (cmd) {
-       case TEST_INIT:
-           info->name = "sample_test";
-           info->category = "main/test/";
-           info->summary = "sample test for example purpose";
-           info->description = "This demonstrates how to initialize a test function";
+      switch (cmd) {
+      case TEST_INIT:
+          info->name = "sample_test";
+          info->category = "main/test/";
+          info->summary = "sample test for example purpose";
+          info->description = "This demonstrates how to initialize a test function";
 
-           return AST_TEST_NOT_RUN;
-       case TEST_EXECUTE:
-           break;
-       }
-	   \test code
-        .
-        .
-        .
-        if (fail) {                 \\ the following is just some example logic
-            ast_str_set(&args->ast_test_error_str, 0 , "an error occured because...");
-            res = AST_RESULT_FAIL;
-        } else {
-            res = AST_RESULT_PASS
-        }
-        return res;                 \\ result must be of type enum ast_test_result_state
-    })
+          return AST_TEST_NOT_RUN;
+      case TEST_EXECUTE:
+          break;
+      }
+      \test code
+      .
+      .
+      .
+      if (fail) {                 \\ the following is just some example logic
+          ast_str_set(&args->ast_test_error_str, 0 , "an error occured because...");
+          res = AST_RESULT_FAIL;
+      } else {
+          res = AST_RESULT_PASS
+      }
+      return res;                 \\ result must be of type enum ast_test_result_state
+   })
 
-    Every callback function is passed ast_test_args object which contains
-	a ast_str allowing the function to provide an optional short description of
-    what went wrong if the test failed. args->ast_test_error_str
+   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.
 
-    *NOTE: It is possible for a ',' within the code body to mess up the macro
-    depending on how it is used.  If this happens (it will be obvious because
-    code won't compile) and can not be avoided, a separate static function must
-    be created to hold the test's code.  In this case the callback's message body
-    should just contain a call to the static function. Any supporting static
-    functions must be wrapped by an '#ifdef TEST_FRAMEWORK' block if they are
-    not also called by another none test defined function.
+   *NOTE: It is possible for a ',' within the code body to mess up the macro
+   depending on how it is used.  If this happens (it will be obvious because
+   code won't compile) and can not be avoided, a separate static function must
+   be created to hold the test's code.  In this case the callback's message body
+   should just contain a call to the static function. Any supporting static
+   functions must be wrapped by an '#ifdef TEST_FRAMEWORK' block if they are
+   not also called by another none test defined function.
 
 2. REGISTER 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
-	to register a test.
+   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
+   for registering a test.
 
-    AST_TEST_REGISTER(sample_test_cb);    \\ Test callback function defined by AST_TEST_DEFINE
+   AST_TEST_REGISTER(sample_test_cb);    \\ Test callback function defined by AST_TEST_DEFINE
 
-    Tests are unregestered by using the AST_TEST_UNREGISTER macro.
+   Tests are unregestered by using the AST_TEST_UNREGISTER macro.
 
-    AST_TEST_UNREGISTER(sample_test_cb);  \\ Remove a registered test by callback function
+   AST_TEST_UNREGISTER(sample_test_cb);  \\ Remove a registered test by callback function
 
 3. EXECUTE: Execute and generate test results via CLI commands
 
-    CLI Examples:
-    '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
+   CLI Examples:
+   '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
 */
 
 /*! Macros used for defining and registering a test */