libusbgx: tests: Add doxygen macros for documenting test cases

Also proceed doxygen config file with autoconf now. Autoconf copy .in file,
substituting found variable values. It allows to specify what documentation
should be build by configure script.

Change-Id: I00cae61aefcc5b6444b0afc0dfe73c5973de34a9
Signed-off-by: Pawel Szewczyk <p.szewczyk@samsung.com>
[Rebase and update description]
Signed-off-by: Krzysztof Opasiak <k.opasiak@samsung.com>

configure.ac

@@ -48,6 +48,6 @@ AS_IF([test "x$enable_gadget_schemes" = xyes],
 AM_CONDITIONAL(TEST_GADGET_SCHEMES, [test "x$enable_gadget_schemes" != xno])
 
 LT_INIT
-AC_CONFIG_FILES([Makefile src/Makefile examples/Makefile libusbgx.pc])
+AC_CONFIG_FILES([Makefile src/Makefile examples/Makefile libusbgx.pc doxygen.cfg])
 DX_INIT_DOXYGEN([$PACKAGE_NAME],[doxygen.cfg])
 AC_OUTPUT

doxygen.cfg.in

@@ -650,6 +650,8 @@ WARN_LOGFILE           =
 
 INPUT                  = $(SRCDIR)/include/usbg/ $(SRCDIR)/src $(SRCDIR)/examples/
 
+@BUILD_TESTS_TRUE@INPUT += $(SRCDIR)/tests/
+
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
 # also the default input encoding. Doxygen uses libiconv (or the iconv built
@@ -1503,7 +1505,7 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator
 # instead of the = operator.
 
-PREDEFINED             =
+PREDEFINED             = DOXYGEN
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.
@@ -1779,3 +1781,8 @@ GENERATE_LEGEND        = YES
 # the various graphs.
 
 DOT_CLEANUP            = YES
+
+ALIASES += tests_start="<table> <tr> <th>Name</th> <th>Description</th> <th>Tested function</th> </tr> \n"
+ALIASES += usbg_test="\page usbg_tests"
+ALIASES += test_desc{3}="<tr> <td>\1</td> <td>\2</td> <td>\ref \3</td> </tr> \n"
+ALIASES += tests_end="</table> "

include/usbg/usbg_internal.h

@@ -24,6 +24,11 @@
 	void config_destroy(config_t *config);
 #endif
 
+/**
+ * @file include/usbg/usbg_internal.h
+ */
+
+
 struct usbg_state
 {
 	char *path;

tests/test.c

@@ -454,55 +454,117 @@ void teardown_state(void **state)
 #define USBG_TEST_TS(name, test, setup) \
 	USBG_TEST(name, test, setup, teardown_state)
 
+/**
+ * @page usbg_tests Tests
+ * @brief This is list of test cases
+ * @tests_start
+ */
+
+#ifndef DOXYGEN
 static UnitTest tests[] = {
-	/* Check if init was successfull on simple configfs state */
+#endif
+
+	/**
+	 * @usbg_test
+	 * @test_desc{test_init_simple,
+	 * Check if init was successfull on simple configfs state,
+	 * usbg_init}
+	 */
 	USBG_TEST_TS("test_init_simple",
 		     test_init, setup_simple_state),
-
-	/* Check if init was successfull when all avaible functions
-	 * are present in configfs */
+	/**
+	 * @usbg_test
+	 * @test_desc{test_init_all_funcs,
+	 * Check if init was successfull when all avaible functions
+	 * are present in configfs,
+	 * usbg_init}
+	 */
 	USBG_TEST_TS("test_init_all_funcs",
 		     test_init, setup_all_funcs_state),
-
-	/* Check if simple gadget will be correcty returned */
+	/**
+	 * @usbg_test
+	 * @test_desc{test_get_gadget_simple,
+	 * Check if simple gadget will be correcty returned,
+	 * usbg_get_gadget}
+	 */
 	USBG_TEST_TS("test_get_gadget_simple",
 		     test_get_gadget, setup_simple_state),
-
-	/* Check if getting non-existing and wrong gadgets cause
-	 * expected failure and error codes are correct */
+	/**
+	 * @usbg_test
+	 * @test_desc{test_get_gadget_fail_simple,
+	 * Check if getting non-existing and wrong gadgets cause
+	 * expected failure and error codes are correct,
+	 * usbg_get_gadget}
+	 */
 	USBG_TEST_TS("test_get_gadget_fail_simple",
 		     test_get_gadget_fail, setup_simple_state),
-
-	/* Check if gadget returned by get_first_gadget
-	 * is actually first one */
+	/**
+	 * @usbg_test
+	 * @test_desc{test_get_first_gadget_simple,
+	 * Check if gadget returned by get_first_gadget
+	 * is actually first one,
+	 * usbg_get_first_gadget}
+	 */
 	USBG_TEST_TS("test_get_first_gadget_simple",
 		     test_get_first_gadget, setup_simple_state),
-
-	/* Check if getting first gadget from state returns NULL when
-	 * invalid parameters are passed */
+	/**
+	 * @usbg_test
+	 * @test_desc{test_get_first_gadget_fail,
+	 * Check if getting first gadget from state returns NULL when
+	 * invalid parameters are passed,
+	 * usbg_get_first_gadget}
+	 */
 	unit_test(test_get_first_gadget_fail),
-
-	/* Check if returned gadget name matches expected value */
+	/**
+	 * @usbg_test
+	 * @test_desc{test_get_gadget_name_simple,
+	 * Check if returned gadget name matches expected value,
+	 * usbg_get_gadget_name}
+	 */
 	USBG_TEST_TS("test_get_gadget_name_simple",
 		     test_get_gadget_name, setup_simple_state),
-
-	/* Check if returned simple gadget name length matches expected value */
+	/**
+	 * @usbg_test
+	 * @test_desc{test_get_gadget_name_len,
+	 * Check if returned simple gadget name length matches expected value,
+	 * usbg_get_gadget_name}
+	 */
 	USBG_TEST_TS("test_get_gadget_name_len_simple",
 		     test_get_gadget_name_len, setup_simple_state),
-
-	/* Check if trying to get name of invalid gadget
-	 * cause expected failure (name is null) */
+	/**
+	 * @usbg_test
+	 * @test_desc{test_get_gadget_name_fail,
+	 * Check if trying to get name of invalid gadget
+	 * cause expected failure (name is null),
+	 * usbg_get_gadget_name}
+	 */
 	unit_test(test_get_gadget_name_fail),
-
-	/* Check if getting simple gadget name into buffer work as expected*/
+	/**
+	 * @usbg_test
+	 * @test_desc{test_cpy_gadget_name_simple,
+	 * Check if getting simple gadget name into buffer work as expected,
+	 * usbg_cpy_gadget_name}
+	 */
 	USBG_TEST_TS("test_cpy_gadget_name_simple",
 		     test_cpy_gadget_name, setup_simple_state),
-
-	/* Check if writting gadget name into buffer fail when
-	 * invalid parameters are passed */
+	/**
+	 * @usbg_test
+	 * @test_desc{test_cpy_gadget_name_fail_simple,
+	 * Check if writting gadget name into buffer fail when
+	 * invalid parameters are passed,
+	 * usbg_cpy_gadget_name}
+	 */
 	USBG_TEST_TS("test_cpy_gadget_name_fail_simple",
 		     test_cpy_gadget_name_fail, setup_simple_state),
+
+#ifndef DOXYGEN
 };
+#endif
+
+/**
+ * @usbg_test
+ * @tests_end
+ */
 
 #define TESTS_TAG "tests"
 /* for autotools compability */

tests/usbg-test.h

@@ -7,6 +7,10 @@
 
 /* Simple structures for defining gadgets. All arrays should be null-terminated.*/
 
+/**
+ * @file tests/usbg-test.h
+ */
+
 struct test_function
 {
 	usbg_function_type type;