Added documentation.

test/test-automation/SDL_test.c

@@ -39,11 +39,11 @@ int _testAssertsFailed;
 int _testAssertsPassed;
 
 void
-_TestCaseInit(const int enable_xml_logging)
+_TestCaseInit(const int enableXMLLogging)
 {
 	// setup logging functions
 	// rather afwul way to do it, but function pointers didn't work
-	if(enable_xml_logging) {
+	if(enableXMLLogging) {
 		SetupXMLLogger();
 	} else {
 		SetupPlainLogger();

test/test-automation/SDL_test.h

@@ -49,14 +49,16 @@ typedef struct TestCaseReference {
 	long timeout;
 } TestCaseReference;
 
-/*! \fn _TestCaseInit
+/*!
  *  Initialized the test case. Must be called at
  *  the beginning of every test case, before doing
  *  anything else.
+ *
+ *  \param enableXMLLogging Whether or not enable xml logging
  */
-void _TestCaseInit(const int enable_xml_logging);
+void _TestCaseInit(const int enableXMLLogging);
 
-/*! \fn _TestCaseQuit
+/*!
  *  Deinitializes and exits the test case
  *
  * \return 0 if test succeeded, otherwise 1

test/test-automation/logger.h

@@ -24,8 +24,8 @@
 #include <time.h>
 
 /*!
- * Generic logger interface
+ * Typedefs for function pointers that implement the  generic
- *
+ * logging interface
  */
 typedef	void (*RunStartedFp)(int parameterCount, char *runnerParameters[], time_t eventTime);
 typedef	void (*RunEndedFp)(int testCount, int suiteCount, int testPassCount, int testFailCount,
@@ -40,10 +40,6 @@ typedef	void (*TestStartedFp)(const char *testName, const char *suiteName,
 typedef	void (*TestEndedFp)(const char *testName, const char *suiteName, int testResult,
                             time_t endTime, double totalRuntime);
 
-/*!
- * Note: for assertResult, non-zero == pass, zero == failure
- *
- */
 typedef	void (*AssertFp)(const char *assertName, int assertResult,
 						 const char *assertMessage, time_t eventTime);
 
@@ -57,6 +53,7 @@ typedef	void (*AssertSummaryFp)(int numAsserts, int numAssertsFailed,
 typedef	void (*LogFp)(const char *logMessage, time_t eventTime);
 
 
+/*! Function pointers to actual logging function implementations */
 extern RunStartedFp RunStarted;
 extern RunEndedFp RunEnded;
 extern SuiteStartedFp SuiteStarted;
@@ -79,7 +76,7 @@ char *IntToString(const int integer);
 /*!
  *  Helper functions. Turns the given double value in to a string
  *
- *  \param integer The converted double value
+ *  \param decimal The converted double value
  *  \returns Given double value as string
  */
 char *DoubleToString(const double decimal);

test/test-automation/plain_logger.h

@@ -3,32 +3,112 @@
 
 #include "logger.h"
 
+/*!
+ * Prints out information about starting the test run.
+ *
+ * \param parameterCount How many parameters were given
+ * \param runnerParameters What parameters were given to the runner
+ * \param eventTime When the execution started
+ */
 void PlainRunStarted(int parameterCount, char *runnerParameters[], time_t eventTime);
 
+/*!
+ * Prints out information about ending the test run.
+ *
+ * \param testCount How many tests were executed in total
+ * \param suiteCount How many suite were executed in total
+ * \param testPassCount How many tests passed in total
+ * \param testFailCount How many tests failed in total
+ * \param endTime When the execution ended
+ * \param totalRuntime How long the execution took
+ */
 void PlainRunEnded(int testCount, int suiteCount, int testPassCount, int testFailCount,
                    time_t endTime, double totalRuntime);
 
+/*!
+ * Prints the data about the test suite that'll be executed next
+ *
+ * \param suiteName Name of the test suite
+ * \param eventTime When the execution starts
+ */
 void PlainSuiteStarted(const char *suiteName, time_t eventTime);
 
+/*!
+ * Prints information about the test suite that was just executed
+ *
+ * \param testsPassed how many tests passed from this suite
+ * \param testsFailed how many tests failed from this suite
+ * \param testsSkipped how many tests were skipped (not implemented)
+ * \param endTime When the suite execution ended
+ * \param totalRuntime How long did the suite's execution take
+ */
 void PlainSuiteEnded(int testsPassed, int testsFailed, int testsSkipped,
            time_t endTime, double totalRuntime);
 
+/*!
+ * Prints the data about the test test that'll be executed next
+ *
+ * \param testName Name of the test that'll be executed
+ * \param suiteName Name of the suite of the test
+ * \param testDescription Description of the test
+ * \param startTime When the test started to execute
+ */
 void PlainTestStarted(const char *testName, const char *suiteName,
                       const char *testDescription, time_t startTime);
 
+/*!
+ * Prints information about the test test that was just executed
+ *
+ * \param testName Name of the executed test
+ * \param suiteName Name of the suite of the test
+ * \param testResult Did the test fail (!= 0) or pass (== 0)
+ * \param endTime When the test execution ended
+ * \param totalRuntime Total runtime of the executed test
+ */
 void PlainTestEnded(const char *testName, const char *suiteName,
           int testResult, time_t endTime, double totalRuntime);
 
 
+/*!
+ * Prints information about plain assert
+ *
+ * \param assertName Name of the assert
+ * \param assertResult Did assert fail (== 0) or success (!= 0)
+ * \param assertMessage Message of the assert
+ * \param eventTime When the assert happened
+ */
 void PlainAssert(const char *assertName, int assertResult, const char *assertMessage,
 				time_t eventTime);
 
+/*!
+ * Prints information about assert that has actual and expected values
+ *
+ * \param assertName Name of the assert
+ * \param assertResult Did assert fail (== 0) or success (!= 0)
+ * \param assertMessage Message of the assert
+ * \param actualValue Actual value of assert
+ * \param expected Excepted value of assert
+ * \param eventTime When the assert happened
+ */
 void PlainAssertWithValues(const char *assertName, int assertResult, const char *assertMessage,
-		int actualValue, int excpected, time_t eventTime);
+		int actualValue, int expected, time_t eventTime);
 
+/*!
+ * Prints summary of all assertions of certain tests
+ *
+ * \param numAsserts Total assert count for the executed test
+ * \param numAssertsFailed Count of failed asserts in the test
+ * \param numAssertsPass Count of passed asserts in the test
+ * \param eventTime Timestamp of the summary
+ */
 void PlainAssertSummary(int numAsserts, int numAssertsFailed, int numAssertsPass, time_t eventTime);
 
-
+/*!
+ * Prints given message
+ *
+ * \param logMessage Message to be logged
+ * \param eventTime Timestamp for log message
+ */
 void PlainLog(const char *logMessage, time_t eventTime);
 
 #endif

test/test-automation/xml_logger.h

@@ -3,30 +3,110 @@
 
 #include "logger.h"
 
+/*!
+ * Prints out information about starting the test run in XML
+ *
+ * \param parameterCount How many parameters were given
+ * \param runnerParameters What parameters were given to the runner
+ * \param eventTime When the execution started
+ */
 void XMLRunStarted(int parameterCount, char *runnerParameters[], time_t eventTime);
 
+/*!
+ * Prints out information about ending the test run in XML
+ *
+ * \param testCount How many tests were executed in total
+ * \param suiteCount How many suite were executed in total
+ * \param testPassCount How many tests passed in total
+ * \param testFailCount How many tests failed in total
+ * \param endTime When the execution ended
+ * \param totalRuntime How long the execution took
+ */
 void XMLRunEnded(int testCount, int suiteCount, int testPassCount, int testFailCount,
                  time_t endTime, double totalRuntime);
 
+/*!
+ * Prints the data about the test suite that'll be executed next in XML
+ *
+ * \param suiteName Name of the test suite
+ * \param eventTime When the execution starts
+ */
 void XMLSuiteStarted(const char *suiteName, time_t eventTime);
 
+/*!
+ * Prints information about the test suite that was just executed in XML
+ *
+ * \param testsPassed how many tests passed from this suite
+ * \param testsFailed how many tests failed from this suite
+ * \param testsSkipped how many tests were skipped (not implemented)
+ * \param endTime When the suite execution ended
+ * \param totalRuntime How long did the suite's execution take
+ */
 void XMLSuiteEnded(int testsPassed, int testsFailed, int testsSkipped,
            time_t endTime, double totalRuntime);
 
+/*!
+ * Prints the data about the test test that'll be executed next in XML
+ *
+ * \param testName Name of the test that'll be executed
+ * \param suiteName Name of the suite of the test
+ * \param testDescription Description of the test
+ * \param startTime When the test started to execute
+ */
 void XMLTestStarted(const char *testName, const char *suiteName, const char *testDescription, time_t startTime);
 
+/*!
+ * Prints information about the test test that was just executed in XML
+ *
+ * \param testName Name of the executed test
+ * \param suiteName Name of the suite of the test
+ * \param testResult Did the test fail (!= 0) or pass (== 0)
+ * \param endTime When the test execution ended
+ * \param totalRuntime Total runtime of the executed test
+ */
 void XMLTestEnded(const char *testName, const char *suiteName,
           int testResult, time_t endTime, double totalRuntime);
 
+/*!
+ * Prints information about plain assert in XML
+ *
+ * \param assertName Name of the assert
+ * \param assertResult Did assert fail (== 0) or success (!= 0)
+ * \param assertMessage Message of the assert
+ * \param eventTime When the assert happened
+ */
 void XMLAssert(const char *assertName, int assertResult, const char *assertMessage,
 			time_t eventTime);
 
+/*!
+ * Prints information about assert that has actual and expected values in XML
+ *
+ * \param assertName Name of the assert
+ * \param assertResult Did assert fail (== 0) or success (!= 0)
+ * \param assertMessage Message of the assert
+ * \param actualValue Actual value of assert
+ * \param expected Excepted value of assert
+ * \param eventTime When the assert happened
+ */
 void XMLAssertWithValues(const char *assertName, int assertResult, const char *assertMessage,
-		int actualValue, int excpected, time_t eventTime);
+		int actualValue, int expected, time_t eventTime);
-
 
+/*!
+ * Prints summary of all assertions of certain tests in XML
+ *
+ * \param numAsserts Total assert count for the executed test
+ * \param numAssertsFailed Count of failed asserts in the test
+ * \param numAssertsPass Count of passed asserts in the test
+ * \param eventTime Timestamp of the summary
+ */
 void XMLAssertSummary(int numAsserts, int numAssertsFailed, int numAssertsPass, time_t eventTime);
 
+/*!
+ * Prints given message in XML
+ *
+ * \param logMessage Message to be logged
+ * \param eventTime Timestamp for log message
+ */
 void XMLLog(const char *logMessage, time_t eventTime);
 
 #endif