code documentation cleaned
authorJan Hutter <jhutter@hsr.ch>
Fri, 25 Nov 2005 09:06:44 +0000 (09:06 -0000)
committerJan Hutter <jhutter@hsr.ch>
Fri, 25 Nov 2005 09:06:44 +0000 (09:06 -0000)
Source/charon/utils/tester.c
Source/charon/utils/tester.h

index 77e9c77..3f278cb 100644 (file)
@@ -1,7 +1,7 @@
 /**
  * @file tester.c
  *
 /**
  * @file tester.c
  *
- * @brief Test module for automatic testing
+ * @brief Implementation of tester_t.
  *
  */
 
  *
  */
 
@@ -40,24 +40,58 @@ typedef struct private_tester_t private_tester_t;
  *
  */
 struct private_tester_t {
  *
  */
 struct private_tester_t {
+       
+       /**
+        * Public interface.
+        */
        tester_t public;
 
 
        /* Private functions */
        tester_t public;
 
 
        /* Private functions */
+       /**
+        * Runs a specific test.
+        * 
+        * @param tester                        associated tester object
+        * @param test_function         test function to perform
+        * @param test_name                     name for the given test
+        */
        void (*run_test) (tester_t *tester, void (*test_function) (tester_t * tester), char * test_name);
 
 
        /* Private values */
        void (*run_test) (tester_t *tester, void (*test_function) (tester_t * tester), char * test_name);
 
 
        /* Private values */
+       /**
+        * Output is written into this file.
+        */
        FILE* output;
        FILE* output;
+       
+       /**
+        * Number of runned tests.
+        */
        int tests_count;
        int tests_count;
+       
+       /**
+        * Number of failed tests.
+        */
        int failed_tests_count;
        int failed_tests_count;
+       
+       /**
+        * Number of failed asserts in curret test.
+        */ 
        int failed_asserts_count;
        int failed_asserts_count;
+       
+       /**
+        * TRUE if succeeded asserts should also be written to output.
+        */
        bool display_succeeded_asserts;
        bool display_succeeded_asserts;
+       
+       /**
+        * Mutex to make this object thread-save.
+        */
        pthread_mutex_t mutex;
 };
 
        pthread_mutex_t mutex;
 };
 
-/*
- * Implementation of function perform_tests
+/**
+ * Implementation of tester_t.perform_tests.
  */
 static status_t perform_tests(tester_t *tester,test_t **tests)
 {
  */
 static status_t perform_tests(tester_t *tester,test_t **tests)
 {
@@ -79,8 +113,8 @@ static status_t perform_tests(tester_t *tester,test_t **tests)
        return SUCCESS;
 }
 
        return SUCCESS;
 }
 
-/*
- * Implementation of function perform_test
+/**
+ * Implementation of tester_t.perform_test.
  */
 static status_t perform_test(tester_t *tester, test_t *test)
 {
  */
 static status_t perform_test(tester_t *tester, test_t *test)
 {
@@ -89,15 +123,17 @@ static status_t perform_test(tester_t *tester, test_t *test)
 }
 
 /**
 }
 
 /**
- * Returns the difference of to timeval structs in microseconds
- *
- * @param end_time end time
- * @param start_time start time
+ * Returns the difference of to timeval structs in microseconds.
  *
  * @warning this function is also defined in the event queue
  *                     in later improvements, this function can be added to a general
  *          class type!
  *
  *
  * @warning this function is also defined in the event queue
  *                     in later improvements, this function can be added to a general
  *          class type!
  *
+ * @param end_time             end time
+ * @param start_time   start time
+ * 
+ * @TODO make object function or move to utils!
+ *
  * @return difference in microseconds
  */
 static long time_difference(struct timeval *end_time, struct timeval *start_time)
  * @return difference in microseconds
  */
 static long time_difference(struct timeval *end_time, struct timeval *start_time)
@@ -111,7 +147,7 @@ static long time_difference(struct timeval *end_time, struct timeval *start_time
 
 
 /**
 
 
 /**
- * Implementation of function run_test
+ * Implementation of private_tester_t.run_test.
  */
 static void run_test(tester_t *tester, void (*test_function) (tester_t * tester), char * test_name)
 {
  */
 static void run_test(tester_t *tester, void (*test_function) (tester_t * tester), char * test_name)
 {
@@ -141,7 +177,7 @@ static void run_test(tester_t *tester, void (*test_function) (tester_t * tester)
  
 
 /**
  
 
 /**
- * Implementation of function assert_true
+ * Implementation of tester_t.assert_true.
  */
 static void assert_true(tester_t *tester, bool to_be_true,char * assert_name)
 {
  */
 static void assert_true(tester_t *tester, bool to_be_true,char * assert_name)
 {
@@ -168,7 +204,7 @@ static void assert_true(tester_t *tester, bool to_be_true,char * assert_name)
 }
 
 /**
 }
 
 /**
- * Implementation of function assert_false
+ * Implementation of tester_t.assert_false.
  */
 static void assert_false(tester_t *tester, bool to_be_false,char * assert_name)
 {
  */
 static void assert_false(tester_t *tester, bool to_be_false,char * assert_name)
 {
@@ -176,7 +212,7 @@ static void assert_false(tester_t *tester, bool to_be_false,char * assert_name)
 }
 
 /**
 }
 
 /**
- * Implements the destroy function
+ * Implementation of tester_t.destroy.
  */
 static status_t destroy(tester_t *tester)
 {
  */
 static status_t destroy(tester_t *tester)
 {
@@ -186,6 +222,9 @@ static status_t destroy(tester_t *tester)
        return SUCCESS;
 }
 
        return SUCCESS;
 }
 
+/*
+ * Described in header.
+ */
 tester_t *tester_create(FILE *output, bool display_succeeded_asserts)
 {
        private_tester_t *this = allocator_alloc_thing(private_tester_t);
 tester_t *tester_create(FILE *output, bool display_succeeded_asserts)
 {
        private_tester_t *this = allocator_alloc_thing(private_tester_t);
index 222b0d4..4352b45 100644 (file)
@@ -1,7 +1,7 @@
 /**
  * @file tester.h
  *
 /**
  * @file tester.h
  *
- * @brief Test module for automatic testing
+ * @brief Interface of tester_t.
  *
  */
 
  *
  */
 
 #include <types.h>
 
 
 #include <types.h>
 
 
-
 typedef struct test_t test_t;
 
 typedef struct tester_t tester_t;
 
 /**
 typedef struct test_t test_t;
 
 typedef struct tester_t tester_t;
 
 /**
- * @brief Specifies a test
+ * @brief Representing a specified test.
+ * 
+ * @ingroup utils
  */
 struct test_t {
  */
 struct test_t {
+       /**
+        * Testfunction called for this test.
+        * 
+        * @param tester                associated tester_t object
+        */
        void (*test_function) (tester_t * tester);
        void (*test_function) (tester_t * tester);
+       /**
+        * Name of the test.
+        */
        char * test_name;
 };
 
 /**
        char * test_name;
 };
 
 /**
- * @brief A tester object to perform tests with
+ * A tester class to perform tests.
+ * 
+ * @ingroup utils
  */
 struct tester_t {
 
        /**
  */
 struct tester_t {
 
        /**
-        * @brief Tests all testcases in array tests with specific tester object
+        * @brief Tests all testcases in array tests with specific tester_t object.
         *
         *
-        * @param tester tester object
-        * @param pointer to a array of test_t-pointers.
-        *                            the last item has to be NULL.
-        * @return SUCCESSFUL if succeeded, FAILED otherwise
+        * @param tester        tester_t object
+        * @param tests         pointer to an array of test_t-pointers.
+        *                              The last item has to be NULL.
+        * @return                      SUCCESS in any case
         */
        status_t (*perform_tests) (tester_t *tester,test_t **tests);
 
        /**
         */
        status_t (*perform_tests) (tester_t *tester,test_t **tests);
 
        /**
-        * @brief run a specific test case
+        * @brief Run a specific test case.
         *
         *
-        * @param this tester object
-        * @param test pointer to a test_t object which will be performed
-        * @param Name of the Test
+        * @param this          tester_t object
+        * @param test          pointer to a test_t object which will be performed
+        * @return                      SUCCESS in any case
         */
        status_t (*perform_test) (tester_t *tester, test_t *test);
 
        /**
         */
        status_t (*perform_test) (tester_t *tester, test_t *test);
 
        /**
-        * @brief is called in a testcase to check a specific situation for TRUE
+        * Is called in a testcase to check a specific situation for TRUE.
         *
         *
-        * Log-Values to the tester output are protected from multiple access
+        * Log-Values to the tester output are protected from multiple access.
         *
         *
-        * @warning this function should only be called in a test_function
+        * @warning This function should only be called in a test_function.
         *
         *
-        * @param this tester object
-        * @param to_be_true assert which has to be TRUE
-        * @param Name of the assertion
+        * @param this                  tester_t object
+        * @param to_be_true    assert which has to be TRUE
+        * @param assert_name   name of the assertion
         */
        void (*assert_true) (tester_t *tester, bool to_be_true, char *assert_name);
 
        /**
         */
        void (*assert_true) (tester_t *tester, bool to_be_true, char *assert_name);
 
        /**
-        * @brief is called in a testcase to check a specific situation for FALSE
+        * Is called in a testcase to check a specific situation for FALSE.
         *
         *
-        * Log-Values to the tester output are protected from multiple access
+        * Log-Values to the tester output are protected from multiple access.
         *
         *
-        * @warning this function should only be called in a test_function
+        * @warning This function should only be called in a test_function.
         *
         *
-        * @param this tester object
-        * @param to_be_false assert which has to be FALSE
-        * @param Name of the assertion
+        * @param this                  tester_t object
+        * @param to_be_false   assert which has to be FALSE
+        * @param assert_name   name of the assertion
         */
        void (*assert_false) (tester_t *tester, bool to_be_false, char *assert_name);
 
        /**
         */
        void (*assert_false) (tester_t *tester, bool to_be_false, char *assert_name);
 
        /**
-        * @brief Destroys a tester object
+        * @brief Destroys a tester_t object
         *
         *
-        * @param tester tester object
-        * @return SUCCESSFUL if succeeded, FAILED otherwise
+        * @param tester        tester_t object
+        * @return                      SUCCESS in any case
         */
        status_t (*destroy) (tester_t *tester);
 };
 
 /**
         */
        status_t (*destroy) (tester_t *tester);
 };
 
 /**
- * @brief creates a tester object needed to perform tests
+ * @brief Creates a tester_t object used to perform tests with.
  *
  *
- * @param output test output is written to this output
+ * @param output                                       test output is written to this output.
  * @param display_succeeded_asserts has to be TRUE, if all asserts should be displayed,
  * @param display_succeeded_asserts has to be TRUE, if all asserts should be displayed,
- *                                                                     else otherwise
+ *                                                                     FALSE otherwise
  *
  *
- * @return tester object
+ * @return                                                     
+ *                                                                     - tester_t object
+ *                                                                     - NULL if out of ressources
+ * 
+ * @ingroup utils
  */
 tester_t *tester_create(FILE *output, bool display_succeeded_asserts);
 
  */
 tester_t *tester_create(FILE *output, bool display_succeeded_asserts);