Added doxygen-compatible comments

test/test-automation/runner.c

@@ -27,7 +27,12 @@
 
 #include "tests/SDL_test.h"
 
-void *LoadLibrary() {
+/*!
+ * Loads test suite which is implemented as dynamic library.
+ *
+ * \return Loaded test suite
+ */
+void *LoadTestSuite() {
 #if defined(linux) || defined( __linux)
 	char *libName = "tests/libtest.so";
 #else
@@ -43,10 +48,16 @@ void *LoadLibrary() {
 	return library;
 }
 
+/*!
+ * Loads the test case references from the given test suite.
+
+ * \param library Previously loaded dynamic library AKA test suite
+ * \return Loaded TestCaseReferences
+ */
 TestCaseReference **QueryTestCases(void *library) {
 	TestCaseReference **(*suite)(void);
 
-	suite = (TestCaseReference **(*)(void)) SDL_LoadFunction(library, "QueryTestCaseReferences");
+	suite = (TestCaseReference **(*)(void)) SDL_LoadFunction(library, "QueryTestSuite");
 	if(suite == NULL) {
 		printf("Loading QueryTestCaseReferences() failed.\n");
 		printf("%s\n", SDL_GetError());
@@ -61,6 +72,21 @@ TestCaseReference **QueryTestCases(void *library) {
 	return tests;
 }
 
+/*
+ *
+ */
+
+/*!
+ * Success or failure of test case is determined by
+ * it's return value. If test case succeeds, it'll
+ * return 0, if not it will return a positive integer.
+ *
+ * The function checks the return value and returns value
+ * based on it. If the test is aborted due to a signal
+ * function warn about it.
+ *
+ * \return 1 if test case succeeded, 0 otherwise
+ */
 int HandleTestReturnValue(int stat_lock) {
 	if(WIFEXITED(stat_lock)) {
 		int returnValue = WEXITSTATUS(stat_lock);
@@ -71,13 +97,8 @@ int HandleTestReturnValue(int stat_lock) {
 	} else if(WIFSIGNALED(stat_lock)) {
 		int signal = WTERMSIG(stat_lock);
 		printf("FAILURE: test was aborted due to signal nro %d\n", signal);
-		//errorMsg =
-		//errorMsg = SDL_malloc(256 * sizeof(char));
-		//sprintf(errorMsg, "was aborted due to signal nro %d", signal);
 
 	} else if(WIFSTOPPED(stat_lock)) {
-		//int signal = WSTOPSIG(stat_lock);
-		//printf("%d: %d was stopped by signal nro %d\n", pid, child, signal);
 	}
 
 	return 0;
@@ -86,7 +107,7 @@ int HandleTestReturnValue(int stat_lock) {
 
 int main(int argc, char *argv[]) {
 
-	// Handle command line arguments
+	//! \todo Handle command line arguments
 
 	// print: Testing againts SDL version fuu (rev: bar)
 
@@ -96,58 +117,59 @@ int main(int argc, char *argv[]) {
 
 	const Uint32 startTicks = SDL_GetTicks();
 
-	void *library = LoadLibrary();
-	TestCaseReference **tests = QueryTestCases(library);
+	void *suite = LoadTestSuite();
+	TestCaseReference **tests = QueryTestCases(suite);
 
 	TestCaseReference *reference = NULL;
 	int counter = 0;
 
-	printf("DEBUG: Starting to run test\n");
-	fflush(stdout);
-
 	for(reference = tests[counter]; reference; reference = tests[++counter]) {
-		char *testname = reference->name;
-		printf("Running %s (in %s):\n", testname, libName);
-
-		int childpid = fork();
-		if(childpid == 0) {
-			void (*test)(void *arg);
-
-			test = (void (*)(void *)) SDL_LoadFunction(library, testname);
-			if(test == NULL) {
-				printf("Loading test failed, tests == NULL\n");
-				printf("%s\n", SDL_GetError());
-			} else {
-				test(0x0);
-			}
-			return 0; // exit the child if the test didn't exit
+		if(reference->enabled == TEST_DISABLED) {
+			printf("Test %s (in %s) disabled. Omitting...\n", reference->name, libName);
 		} else {
-			int stat_lock = -1;
-			int child = wait(&stat_lock);
+			char *testname = reference->name;
+
+			printf("Running %s (in %s):\n", testname, libName);
+
+			int childpid = fork();
+			if(childpid == 0) {
+				void (*test)(void *arg);
+
+				test = (void (*)(void *)) SDL_LoadFunction(suite, testname);
+				if(test == NULL) {
+					printf("Loading test failed, tests == NULL\n");
+					printf("%s\n", SDL_GetError());
+				} else {
+					test(0x0);
+				}
+				return 0; // exit the child if the test didn't exit
+			} else {
+				int stat_lock = -1;
+				int child = wait(&stat_lock);
 
-			int passed = -1;
+				int passed = -1;
 
-			passed = HandleTestReturnValue(stat_lock);
+				passed = HandleTestReturnValue(stat_lock);
 
-			if(passed) {
-				passCount++;
-				printf("%s (in %s): ok\n", testname, libName);
-			} else {
-				failureCount++;
-				printf("%s (in %s): failed\n", testname, libName);
+				if(passed) {
+					passCount++;
+					printf("%s (in %s): ok\n", testname, libName);
+				} else {
+					failureCount++;
+					printf("%s (in %s): failed\n", testname, libName);
+				}
 			}
 		}
 
 		printf("\n");
 	}
 	
-	SDL_UnloadObject(library);
+	SDL_UnloadObject(suite);
 
 	const Uint32 endTicks = SDL_GetTicks();
 
 	printf("Ran %d tests in %0.3f seconds.\n", (passCount + failureCount), (endTicks-startTicks)/1000.0f);
 
-	printf("all tests executed\n");
 	printf("%d tests passed\n", passCount);
 	printf("%d tests failed\n", failureCount);
 

test/test-automation/tests/SDL_test.c

@@ -25,16 +25,17 @@
 
 #include <stdlib.h>
 
+/*! \brief return value of test case. Non-zero value means that the test failed */
 static int _testReturnValue;
 
 void
-TestInit()
+TestCaseInit()
 {
 	_testReturnValue = 0;
 }
 
 void
-TestQuit()
+TestCaseQuit()
 {
 	exit(_testReturnValue);
 }

test/test-automation/tests/SDL_test.h

@@ -23,15 +23,34 @@
 
 #include <SDL/SDL.h>
 
+// \todo Should these be consts?
+#define TEST_ENABLED  1
+#define TEST_DISABLED 0
+
+
+/*!
+ * Holds information about a test case
+ */
 typedef struct TestCaseReference {
-	char *name;         /* "Func2Stress" */
-	char *description;  /* "This test beats the crap out of func2()" */
-	int enabled;       /* Set to TEST_ENABLED or TEST_DISABLED */
-	long requirements;  /* Set to TEST_REQUIRES_OPENGL, TEST_REQUIRES_AUDIO, ... */
+	char *name;         /*!< "Func2Stress" */
+	char *description;  /*!< "This test beats the crap out of func2()" */
+	int enabled;       /*!< Set to TEST_ENABLED or TEST_DISABLED */
+	long requirements;  /*!< Set to TEST_REQUIRES_OPENGL, TEST_REQUIRES_AUDIO, ... */
 } TestCaseReference;
 
-void TestInit();
-void TestQuit();
+/*! \fn TestCaseInit
+ *  Initialized the test case. Must be called at
+ *  the beginning of every test case, before doing
+ *  anything else.
+ */
+void TestCaseInit();
+
+/*! \fn TestCaseQuit
+ *  Deinitializes and exits the test case
+ *
+ */
+void TestCaseQuit();
+
 
 void AssertEquals(char *message, Uint32 expected, Uint32 actual);
 

test/test-automation/tests/test.c

@@ -28,50 +28,56 @@
 #include "SDL_test.h"
 
 /* Test cases */
-static const TestCaseReference test1 = 
-		(TestCaseReference){ "hello", "description", 1, 0 };
+static const TestCaseReference test1 =
+		(TestCaseReference){ "hello", "description", TEST_ENABLED, 0 };
 
-static const TestCaseReference test2 = 
-		(TestCaseReference){ "hello2", "description", 1, 0 };
+static const TestCaseReference test2 =
+		(TestCaseReference){ "hello2", "description", TEST_DISABLED, 0 };
+
+static const TestCaseReference test3 =
+		(TestCaseReference){ "hello3", "description", TEST_ENABLED, 0 };
 
 /* Test suite */
 extern const TestCaseReference *testSuite[] =  {
-	&test1, &test2, NULL
+	&test1, &test2, &test3, NULL
 };
 
 
-TestCaseReference **QueryTestCaseReferences() {
+TestCaseReference **QueryTestSuite() {
 	return (TestCaseReference **)testSuite;
 }
 
-void hello(void *arg){
-	TestInit();
+/* Test case functions */
+void hello(void *arg)
+{
+	TestCaseInit();
 
 	const char *revision = SDL_GetRevision();
 
 	printf("Revision is %s\n", revision);
 	AssertEquals("will fail", 3, 5);
 
-	TestQuit();
+	TestCaseQuit();
 }
 
-void hello2(void *arg) {
-	TestInit();
+void hello2(void *arg)
+{
+	TestCaseInit();
 
-	// why this isn't segfaulting?
 	char *msg = "eello";
 	msg[0] = 'H';
 
-	TestQuit();
+	TestCaseQuit();
 }
 
-void hello3(void *arg) {
-	TestInit();
+void hello3(void *arg)
+{
+	TestCaseInit();
 	printf("hello3\n");
 
 	AssertEquals("passes", 3, 3);
 
-	TestQuit();
+	TestCaseQuit();
 }
 
 #endif