diff -r ae5a98f0545c -r 88625853ae74 ucx/test.h
--- a/ucx/test.h	Sat Dec 01 20:34:55 2012 +0100
+++ b/ucx/test.h	Mon Aug 12 14:40:19 2013 +0200
@@ -1,90 +1,223 @@
-/* 
- * File:   test.h
- * Author: Mike
+/*
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+ *
+ * Copyright 2013 Olaf Wintermann. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ *   1. Redistributions of source code must retain the above copyright
+ *      notice, this list of conditions and the following disclaimer.
+ *
+ *   2. Redistributions in binary form must reproduce the above copyright
+ *      notice, this list of conditions and the following disclaimer in the
+ *      documentation and/or other materials provided with the distribution.
  *
- * Created on 18. Februar 2012, 14:15
- *
- *
- *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+ 
+/**
+ * @file: test.h
+ * 
+ * UCX Test Framework.
+ * 
  * Usage of this test framework:
  *
  * **** IN HEADER FILE: ****
  *
- * UCX_TEST_DECLARE(function_name)
+ * <pre>
+ * UCX_TEST(function_name)
+ * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) // optional
+ * </pre>
  *
  * **** IN SOURCE FILE: ****
+ * <pre>
+ * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) {
+ *   // tests with UCX_TEST_ASSERT()
+ * }
+ * 
+ * UCX_TEST(function_name) {
+ *   // memory allocation and other stuff here
+ *   #UCX_TEST_BEGIN
+ *   // tests with UCX_TEST_ASSERT() and/or
+ *   // calls with UCX_TEST_CALL_SUBROUTINE() here
+ *   #UCX_TEST_END
+ *   // cleanup of memory here
+ * }
+ * </pre>
  *
- * UCX_TEST_IMPLEMENT(function_name) {
- *  <memory allocation and other stuff here>
- *  UCX_TEST_BEGIN
- *  <tests with UCX_TEST_ASSERT here>
- *  UCX_TEST_END
- *  <cleanup of memory here>
- * }
+ * <b>Note:</b> if a test fails, a longjump is performed
+ * back to the #UCX_TEST_BEGIN macro!
+ * 
+ * <b>Attention:</b> Do not call own functions within a test, that use
+ * UCX_TEST_ASSERT() macros and are not defined by using UCX_TEST_SUBROUTINE().
+ * 
  *
- * PLEASE NOTE: if a test fails, a longjump is performed
- * back to the UCX_TEST_BEGIN macro!
- *
- * You may use multiple BEGIN-END blocks if you are aware of the
- * longjmp behaviour.
+ * @author Mike Becker
+ * @author Olaf Wintermann
  *
  */
 
-#ifndef TEST_H
-#define	TEST_H
+#ifndef UCX_TEST_H
+#define	UCX_TEST_H
 
 #include "ucx.h"
 #include <stdio.h>
 #include <string.h>
 #include <setjmp.h>
-#include "list.h"
 
 #ifdef	__cplusplus
 extern "C" {
 #endif
 
 #ifndef __FUNCTION__
+/**
+ * Alias for the <code>__func__</code> preprocessor macro.
+ * Some compilers use <code>__func__</code> and others use __FUNC__.
+ * We use __FUNC__ so we define it for those compilers which use
+ * <code>__func__</code>.
+ */
 #define __FUNCTION__ __func__
 #endif
 
-typedef struct {
-    unsigned int success;
-    unsigned int failure;
-    UcxList *tests;
-} UcxTestSuite;
-
+/** Type for the internal list of test cases. */
+typedef struct UcxTestList UcxTestList;
+/** Type for the UcxTestSuite. */
+typedef struct UcxTestSuite UcxTestSuite;
+/** Pointer to a test function. */
 typedef void(*UcxTest)(UcxTestSuite*,FILE*);
 
+/**
+ * A test suite containing multiple test cases.
+ */
+struct UcxTestSuite {
+    /** The number of successful tests after the suite has been run. */
+    unsigned int success;
+    /** The number of failed tests after the suite has been run. */
+    unsigned int failure;
+    /**
+     * Internal list of test cases.
+     * Use ucx_test_register() to add tests to this list.
+     */
+    UcxTestList *tests;
+};
+
+/**
+ * Creates a new test suite.
+ * @return a new test suite
+ */
 UcxTestSuite* ucx_test_suite_new();
-void ucx_test_suite_free(UcxTestSuite*);
+/**
+ * Destroys a test suite.
+ * @param the test suite to destroy
+ */
+void ucx_test_suite_free(UcxTestSuite* suite);
 
-void ucx_test_register(UcxTestSuite*, UcxTest);
-void ucx_test_run(UcxTestSuite*, FILE*);
+/**
+ * Registers a test function with the specified test suite.
+ * 
+ * @param suite the suite, the test function shall be added to
+ * @param test the test function to register
+ * @return <code>EXIT_SUCCESS</code> on success or
+ * <code>EXIT_FAILURE</code> on failure
+ */
+int ucx_test_register(UcxTestSuite* suite, UcxTest test);
+/**
+ * Runs a test suite and writes the test log to the specified stream.
+ * @param suite the test suite to run
+ * @param outstream the stream the log shall be written to
+ */
+void ucx_test_run(UcxTestSuite* suite, FILE* outstream);
 
-#define UCX_TEST_DECLARE(name) void name(UcxTestSuite*,FILE *)
-#define UCX_TEST_IMPLEMENT(name) void name(UcxTestSuite* _suite_,FILE *_output_)
+/**
+ * Macro for a #UcxTest function header.
+ * 
+ * Use this macro to declare and/or define an #UcxTest function.
+ * 
+ * @param name the name of the test function
+ */
+#define UCX_TEST(name) void name(UcxTestSuite* _suite_,FILE *_output_)
 
+/**
+ * Marks the begin of a test.
+ * <b>Note:</b> Any UCX_TEST_ASSERT() calls must be performed <b>after</b>
+ * #UCX_TEST_BEGIN.
+ * 
+ * @see #UCX_TEST_END
+ */
 #define UCX_TEST_BEGIN fwrite("Running ", 1, 8, _output_);\
         fwrite(__FUNCTION__, 1, strlen(__FUNCTION__), _output_);\
         fwrite("... ", 1, 4, _output_);\
         jmp_buf _env_; \
         if (!setjmp(_env_)) {
 
+/**
+ * Checks a test assertion.
+ * If the assertion is correct, the test carries on. If the assertion is not
+ * correct, the specified message (terminated by a dot and a line break) is
+ * written to the test suites output stream.
+ * @param condition the condition to check
+ * @param message the message that shall be printed out on failure
+ */
 #define UCX_TEST_ASSERT(condition,message) if (!(condition)) { \
         fwrite(message".\n", 1, 2+strlen(message), _output_); \
         _suite_->failure++; \
         longjmp(_env_, 1);\
     }
 
-#define UCX_TEST_SUBROUTINE(name,data) void name(UcxTestSuite* _suite_,\
-        FILE *_output_, jmp_buf _env_, void* data)
-#define UCX_TEST_CALL_SUBROUTINE(name,data) name(_suite_,_output_,_env_,data);
+/**
+ * Macro for a test subroutine function header.
+ * 
+ * Use this to declare and/or define an subroutine that can be called by using
+ * UCX_TEST_CALL_SUBROUTINE().
+ * 
+ * @param name the name of the subroutine
+ * @param ... the parameter list
+ * 
+ * @see UCX_TEST_CALL_SUBROUTINE()
+ */
+#define UCX_TEST_SUBROUTINE(name,...) void name(UcxTestSuite* _suite_,\
+        FILE *_output_, jmp_buf _env_, __VA_ARGS__)
 
+/**
+ * Macro for calling a test subroutine.
+ * 
+ * Subroutines declared with UCX_TEST_SUBROUTINE() can be called by using this
+ * macro.
+ * 
+ * <b>Note:</b> You may <b>only</b> call subroutines within a #UCX_TEST_BEGIN-
+ * #UCX_TEST_END-block.
+ * 
+ * @param name the name of the subroutine
+ * @param ... the argument list
+ * 
+ * @see UCX_TEST_SUBROUTINE()
+ */
+#define UCX_TEST_CALL_SUBROUTINE(name,...) \
+        name(_suite_,_output_,_env_,__VA_ARGS__);
+
+/**
+ * Marks the end of a test.
+ * <b>Note:</b> Any UCX_TEST_ASSERT() calls must be performed <b>before</b>
+ * #UCX_TEST_END.
+ * 
+ * @see #UCX_TEST_BEGIN
+ */
 #define UCX_TEST_END fwrite("success.\n", 1, 9, _output_); _suite_->success++;}
 
 #ifdef	__cplusplus
 }
 #endif
 
-#endif	/* TEST_H */
+#endif	/* UCX_TEST_H */