tests: doxygen comment cleanup

Group tests under 'Zephyr Tests' and only document the actual tests.
Create cross references to APIs being tested where applicable.

Signed-off-by: Anas Nashif <anas.nashif@intel.com>

tests/kernel/alert/alert_api/src/main.c

@@ -9,11 +9,6 @@
  * @brief Verify zephyr alert send/recv across different contexts
  */
 
-/**
- * @brief Tests for the Alert kernel object
- * @defgroup kernel.alerts
- * @{
- */
 #include <ztest.h>
 #include <irq_offload.h>
 
@@ -139,6 +134,18 @@ static void isr_alert(void)
 	alert_recv();
 }
 
+int event_handler(struct k_alert *alt)
+{
+	return handler_val;
+}
+
+/**
+ * @brief Tests for the Alert kernel object
+ * @defgroup kernel_alerts Alerts
+ * @ingroup all_tests
+ * @{
+ */
+
 /**
  * @brief Test thread alert default
  *
@@ -397,11 +404,6 @@ void test_thread_alert_wait(void)
 	}
 }
 
-int event_handler(struct k_alert *alt)
-{
-	return handler_val;
-}
-
 /**
  * @brief Test thread alert handler
  *
@@ -434,6 +436,9 @@ void test_thread_alert_handler(void)
 
 	zassert_equal(ret, 0, NULL);
 }
+/**
+ * @}
+ */
 
 
 /**
@@ -498,6 +503,3 @@ void test_main(void)
 			 ztest_unit_test(test_isr_kinit_alert));
 	ztest_run_test_suite(alert_api);
 }
-/**
- * @}
- */

tests/kernel/fifo/fifo_api/src/main.c

@@ -5,9 +5,18 @@
  */
 
 /**
- * @addtogroup t_fifo
+ * @brief Tests for the FIFO kernel object
+ *
+ * Verify zephyr fifo apis under different context
+ *
+ * - API coverage
+ *   -# k_fifo_init K_FIFO_DEFINE
+ *   -# k_fifo_put k_fifo_put_list k_fifo_put_slist
+ *   -# k_fifo_get *
+ *
+ * @defgroup kernel_fifo FIFOs
+ * @ingroup all_tests
  * @{
- * @defgroup t_fifo_api test_fifo_api
  * @}
  */
 

tests/kernel/fifo/fifo_api/src/test_fifo_cancel.c

@@ -50,7 +50,10 @@ static void tfifo_thread_thread(struct k_fifo *pfifo)
 		     "k_fifo_get didn't get cancelled in expected timeframe");
 }
 
-/*test cases*/
+/**
+ * @addtogroup kernel_fifo
+ * @{
+ */
 void test_fifo_cancel_wait(void)
 {
 	/**TESTPOINT: init via k_fifo_init*/
@@ -60,3 +63,7 @@ void test_fifo_cancel_wait(void)
 	/**TESTPOINT: test K_FIFO_DEFINEed fifo*/
 	tfifo_thread_thread(&kfifo_c);
 }
+
+/**
+ * @}
+ */

tests/kernel/fifo/fifo_api/src/test_fifo_contexts.c

@@ -4,18 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @addtogroup t_fifo_api
- * @{
- * @defgroup t_fifo_api_basic test_fifo_api_basic
- * @brief TestPurpose: verify zephyr fifo apis under different context
- * - API coverage
- *   -# k_fifo_init K_FIFO_DEFINE
- *   -# k_fifo_put k_fifo_put_list k_fifo_put_slist
- *   -# k_fifo_get
- * @}
- */
-
 #include "test_fifo.h"
 
 #define STACK_SIZE (512 + CONFIG_TEST_EXTRA_STACKSIZE)
@@ -137,7 +125,10 @@ static void tfifo_is_empty(void *p)
 	zassert_true(k_fifo_is_empty(pfifo), NULL);
 }
 
-/*test cases*/
+/**
+ * @addtogroup kernel_fifo
+ * @{
+ */
 void test_fifo_thread2thread(void)
 {
 	/**TESTPOINT: init via k_fifo_init*/
@@ -184,3 +175,6 @@ void test_fifo_is_empty_isr(void)
 	/**TESTPOINT: check fifo is empty from isr*/
 	irq_offload(tfifo_is_empty, &fifo);
 }
+/**
+ * @}
+ */

tests/kernel/fifo/fifo_api/src/test_fifo_fail.c

@@ -4,22 +4,18 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @addtogroup t_fifo_api
- * @{
- * @defgroup t_fifo_get_fail test_fifo_get_fail
- * @brief TestPurpose: verify zephyr fifo_get when no data
- * - API coverage
- *   -# k_fifo_init
- *   -# k_fifo_get
- * @}
- */
-
 #include "test_fifo.h"
 
 #define TIMEOUT 100
 
-/*test cases*/
+/**
+ * @addtogroup kernel_fifo
+ * @{
+ * @brief Verify zephyr fifo_get when no data
+ * - API coverage
+ *   -# k_fifo_init
+ *   -# k_fifo_get
+ */
 void test_fifo_get_fail(void *p1, void *p2, void *p3)
 {
 	struct k_fifo fifo;
@@ -29,4 +25,6 @@ void test_fifo_get_fail(void *p1, void *p2, void *p3)
 	zassert_is_null(k_fifo_get(&fifo, K_NO_WAIT), NULL);
 	zassert_is_null(k_fifo_get(&fifo, TIMEOUT), NULL);
 }
-
+/**
+ * @}
+ */

tests/kernel/fifo/fifo_api/src/test_fifo_loop.c

@@ -4,28 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @addtogroup t_fifo_api
- * @{
- * @defgroup t_fifo_loop test_fifo_loop
- * @brief TestPurpose: verify zephyr fifo continuous read write
- *                     in loop
- * @details
- * - Test Steps
- *   -# fifo put from main thread
- *   -# fifo read from isr
- *   -# fifo put from isr
- *   -# fifo get from spawn thread
- *   -# loop above steps for LOOPs times
- * - Expected Results
- *   -# fifo data pass correctly and stably across contexts
- * - API coverage
- *   -# k_fifo_init
- *   -# k_fifo_put
- *   -# k_fifo_get
- * @}
- */
-
 #include "test_fifo.h"
 
 #define STACK_SIZE (512 + CONFIG_TEST_EXTRA_STACKSIZE)
@@ -98,7 +76,25 @@ static void tfifo_read_write(struct k_fifo *pfifo)
 	TC_PRINT("\n");
 }
 
-/*test cases*/
+/**
+ * @brief Verify zephyr fifo continuous read write in loop
+ *
+ * @details
+ * - Test Steps
+ *   -# fifo put from main thread
+ *   -# fifo read from isr
+ *   -# fifo put from isr
+ *   -# fifo get from spawn thread
+ *   -# loop above steps for LOOPs times
+ * - Expected Results
+ *   -# fifo data pass correctly and stably across contexts
+ * - API coverage
+ *   -# k_fifo_init
+ *   -# k_fifo_put
+ *   -# k_fifo_get
+ * @addtogroup kernel_fifo
+ * @{
+ */
 void test_fifo_loop(void)
 {
 	k_fifo_init(&fifo);
@@ -107,3 +103,6 @@ void test_fifo_loop(void)
 		tfifo_read_write(&fifo);
 	}
 }
+/**
+ * @}
+ */

tests/kernel/msgq/msgq_api/src/main.c

@@ -5,9 +5,9 @@
  */
 
 /**
- * @addtogroup t_kernel_msgq
+ * @defgroup kernel_message_queue Message Queue
+ * @ingroup all_tests
  * @{
- * @defgroup t_msgq_api test_msgq_api
  * @}
  */
 

tests/kernel/msgq/msgq_api/src/test_msgq_attrs.c

@@ -4,20 +4,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @addtogroup t_msgq_api
- * @{
- * @defgroup t_msgq_attrs test_msgq_attrs
- * @brief TestPurpose: verify zephyr msgq get attributes API.
- * @}
- */
-
 #include "test_msgq.h"
 extern struct k_msgq msgq;
 static char __aligned(4) tbuffer[MSG_SIZE * MSGQ_LEN];
 static u32_t send_buf[MSGQ_LEN] = { MSG0, MSG1 };
 static u32_t rec_buf[MSGQ_LEN] = { MSG0, MSG1 };
 
+/**
+ * @brief Verify zephyr msgq get attributes API.
+ * @addtogroup kernel_message_queue
+ * @{
+ */
 void test_msgq_attrs_get(void)
 {
 	int ret;
@@ -45,3 +42,6 @@ void test_msgq_attrs_get(void)
 	k_msgq_get_attrs(&msgq, &attrs);
 	zassert_equal(attrs.used_msgs, 0, NULL);
 }
+/**
+ * @}
+ */

tests/kernel/msgq/msgq_api/src/test_msgq_contexts.c

@@ -4,14 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @addtogroup t_kernel_msgq
- * @{
- * @defgroup t_msgq_context test_msgq_context
- * @brief TestPurpose: verify zephyr msgq apis across contexts
- * @}
- */
-
 #include "test_msgq.h"
 
 /**TESTPOINT: init via K_MSGQ_DEFINE*/
@@ -139,8 +131,11 @@ static void msgq_isr(struct k_msgq *pmsgq)
 	/**TESTPOINT: msgq purge*/
 	purge_msgq(pmsgq);
 }
-
-/*test cases*/
+/**
+ * @brief Verify zephyr msgq apis across contexts
+ * @addtogroup kernel_message_queue
+ * @{
+ */
 void test_msgq_thread(void)
 {
 	/**TESTPOINT: init via k_msgq_init*/
@@ -171,3 +166,7 @@ void test_msgq_isr(void)
 	msgq_isr(&stack_msgq);
 	msgq_isr(&kmsgq);
 }
+
+/**
+ * @}
+ */

tests/kernel/msgq/msgq_api/src/test_msgq_fail.c

@@ -3,23 +3,17 @@
  *
  * SPDX-License-Identifier: Apache-2.0
  */
-
-/**
- * @addtogroup t_msgq_api
- * @{
- * @defgroup t_msgq_fail test_msgq_fail
- * @brief TestPurpose: verify zephyr msgq return code under negative tests
- * @}
- */
-
-
 #include "test_msgq.h"
 
 static char __aligned(4) tbuffer[MSG_SIZE * MSGQ_LEN];
 static u32_t data[MSGQ_LEN] = { MSG0, MSG1 };
 extern struct k_msgq msgq;
 
-/*test cases*/
+/**
+ * @brief Verify zephyr msgq return code under negative tests
+ * @addtogroup kernel_message_queue
+ * @{
+ */
 void test_msgq_put_fail(void *p1, void *p2, void *p3)
 {
 	k_msgq_init(&msgq, tbuffer, MSG_SIZE, MSGQ_LEN);
@@ -52,3 +46,7 @@ void test_msgq_get_fail(void *p1, void *p2, void *p3)
 	ret = k_msgq_get(&msgq, &rx_data, TIMEOUT);
 	zassert_equal(ret, -EAGAIN, NULL);
 }
+
+/**
+ * @}
+ */

tests/kernel/msgq/msgq_api/src/test_msgq_purge.c

@@ -4,15 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-/**
- * @addtogroup t_msgq_api
- * @{
- * @defgroup t_msgq_purge test_msgq_purge
- * @brief TestPurpose: verify zephyr msgq purge under different scenario
- * @}
- */
-
-
 #include "test_msgq.h"
 
 K_THREAD_STACK_EXTERN(tstack);
@@ -28,7 +19,11 @@ static void tThread_entry(void *p1, void *p2, void *p3)
 	zassert_equal(ret, -ENOMSG, NULL);
 }
 
-/*test cases*/
+/**
+ * @brief Verify zephyr msgq purge under different scenario
+ * @addtogroup kernel_message_queue
+ * @{
+ */
 void test_msgq_purge_when_put(void)
 {
 	int ret;
@@ -54,3 +49,6 @@ void test_msgq_purge_when_put(void)
 		zassert_equal(ret, 0, NULL);
 	}
 }
+/**
+ * @}
+ */

tests/kernel/systhreads/src/main.c

@@ -24,7 +24,13 @@ int _sys_soc_suspend(s32_t ticks)
 	return 0;
 }
 
-/* test cases */
+/**
+ * @brief System Thread Test Cases
+ * @defgroup kernel_systemthreads System Threads
+ * @ingroup all_tests
+ * @brief Verify 2 system threads - main thread and idle thread
+ * @{
+ */
 void test_systhreads_setup(void)
 {
 	main_prio = k_thread_priority_get(k_current_get());
@@ -42,7 +48,9 @@ void test_systhreads_idle(void)
 	zassert_true(k_thread_priority_get(k_current_get()) <
 			K_IDLE_PRIO, NULL);
 }
-
+/**
+ * @}
+ */
 void test_main(void)
 {
 	test_systhreads_setup();

tests/ztest/include/ztest.h

@@ -10,6 +10,13 @@
  * @brief Zephyr testing suite
  */
 
+/**
+ * @brief Zephyr Tests
+ * @defgroup all_tests Zephyr Tests
+ * @{
+ * @}
+ */
+
 #ifndef __ZTEST_H__
 #define __ZTEST_H__