From 7b3ed2fbb421ca1a5fe8f057ed3e261022a2f135 Mon Sep 17 00:00:00 2001 From: Anas Nashif Date: Thu, 17 Apr 2025 12:05:33 -0400 Subject: [PATCH] tests: kernel/common: cleanup doxygen Fix grouping and general doxygen fixups. Signed-off-by: Anas Nashif --- tests/kernel/common/src/atomic.c | 14 +++++++----- tests/kernel/common/src/bitarray.c | 12 ++++++---- tests/kernel/common/src/bitfield.c | 15 ++++++++----- tests/kernel/common/src/boot_delay.c | 14 +++++++----- tests/kernel/common/src/byteorder.c | 15 +++++++++---- tests/kernel/common/src/clock.c | 13 +++++++---- tests/kernel/common/src/constructor.c | 22 +++++++++++-------- tests/kernel/common/src/errno.c | 29 +++++++++++-------------- tests/kernel/common/src/irq_offload.c | 19 ++++++++++++---- tests/kernel/common/src/printk.c | 12 +++++++--- tests/kernel/common/src/timeout_order.c | 14 +++++++----- 11 files changed, 114 insertions(+), 65 deletions(-) diff --git a/tests/kernel/common/src/atomic.c b/tests/kernel/common/src/atomic.c index 1bdbfe3bf5c..fb88900a1eb 100644 --- a/tests/kernel/common/src/atomic.c +++ b/tests/kernel/common/src/atomic.c @@ -28,7 +28,12 @@ static struct k_thread thread[THREADS_NUM]; atomic_t total_atomic; /** - * @addtogroup kernel_common_tests + * @defgroup kernel_atomic_ops_tests Atomic Operations + * @ingroup all_tests + * @{ + * @} + * + * @addtogroup kernel_atomic_ops_tests * @{ */ @@ -92,7 +97,6 @@ atomic_t total_atomic; * atomic_test_and_set_bit(), atomic_clear_bit(), atomic_set_bit(), * ATOMIC_DEFINE * - * @ingroup kernel_common_tests */ ZTEST_USER(atomic, test_atomic) { @@ -312,7 +316,6 @@ void atomic_handler(void *p1, void *p2, void *p3) * In this time, the two sub threads will be scheduled separately * according to the time slice. * - * @ingroup kernel_common_tests */ ZTEST(atomic, test_threads_access_atomic) { @@ -349,7 +352,6 @@ ZTEST(atomic, test_threads_access_atomic) * in a non-atomic manner (as long as it is logically safe) * and expect its value to match the result of the similar atomic increment. * - * @ingroup kernel_common_tests */ ZTEST(atomic, test_atomic_overflow) { @@ -383,8 +385,8 @@ ZTEST(atomic, test_atomic_overflow) atomic_value); } -extern void *common_setup(void); -ZTEST_SUITE(atomic, NULL, common_setup, NULL, NULL, NULL); /** * @} */ +extern void *common_setup(void); +ZTEST_SUITE(atomic, NULL, common_setup, NULL, NULL, NULL); diff --git a/tests/kernel/common/src/bitarray.c b/tests/kernel/common/src/bitarray.c index a7a7be02a01..acac6efdf51 100644 --- a/tests/kernel/common/src/bitarray.c +++ b/tests/kernel/common/src/bitarray.c @@ -22,7 +22,12 @@ #define BITFIELD_SIZE 512 /** - * @addtogroup kernel_common_tests + * @defgroup kernel_bitarray_tests Bit Arrays + * @ingroup all_tests + * @{ + * @} + * + * @addtogroup kernel_bitarray_tests * @{ */ @@ -1058,9 +1063,8 @@ ZTEST(bitarray, test_ffs) zassert_equal(find_lsb_set(value), bit + 1, "LSB is not matched"); } } -extern void *common_setup(void); -ZTEST_SUITE(bitarray, NULL, common_setup, NULL, NULL, NULL); - /** * @} */ +extern void *common_setup(void); +ZTEST_SUITE(bitarray, NULL, common_setup, NULL, NULL, NULL); diff --git a/tests/kernel/common/src/bitfield.c b/tests/kernel/common/src/bitfield.c index 84e0258a872..c62627a7ebd 100644 --- a/tests/kernel/common/src/bitfield.c +++ b/tests/kernel/common/src/bitfield.c @@ -19,7 +19,12 @@ #define BITFIELD_SIZE 512 /** - * @addtogroup kernel_common_tests + * @defgroup kernel_bitfield_tests Bit Fields + * @ingroup all_tests + * @{ + * @} + * + * @addtogroup kernel_bitfield_tests * @{ */ @@ -131,10 +136,10 @@ ZTEST(bitfield, test_bitfield) } -extern void *common_setup(void); - -ZTEST_SUITE(bitfield, NULL, common_setup, NULL, NULL, NULL); - /** * @} */ + +extern void *common_setup(void); + +ZTEST_SUITE(bitfield, NULL, common_setup, NULL, NULL, NULL); diff --git a/tests/kernel/common/src/boot_delay.c b/tests/kernel/common/src/boot_delay.c index 7d4e44630fa..62e9c20fb58 100644 --- a/tests/kernel/common/src/boot_delay.c +++ b/tests/kernel/common/src/boot_delay.c @@ -6,11 +6,15 @@ #include + /** - * @brief Test delay during boot - * @defgroup kernel_init_tests Init + * @defgroup kernel_init_tests Kernel Initialization * @ingroup all_tests * @{ + * @} + * + * @addtogroup kernel_init_tests + * @{ */ /** @@ -39,9 +43,9 @@ ZTEST(boot_delay, test_bootdelay) (NSEC_PER_MSEC * CONFIG_BOOT_DELAY)); } -extern void *common_setup(void); -ZTEST_SUITE(boot_delay, NULL, common_setup, NULL, NULL, NULL); - /** * @} */ + +extern void *common_setup(void); +ZTEST_SUITE(boot_delay, NULL, common_setup, NULL, NULL, NULL); diff --git a/tests/kernel/common/src/byteorder.c b/tests/kernel/common/src/byteorder.c index a888ad1f1e0..6998360a660 100644 --- a/tests/kernel/common/src/byteorder.c +++ b/tests/kernel/common/src/byteorder.c @@ -10,9 +10,15 @@ #include /** - * @addtogroup kernel_common_tests + * @defgroup kernel_byteorder_tests Byteorder Operations + * @ingroup all_tests + * @{ + * @} + * + * @addtogroup kernel_byteorder_tests * @{ */ + /** * @brief Test swapping for memory contents * @@ -704,9 +710,10 @@ ZTEST(byteorder, test_sys_get_be) zassert_mem_equal(host, exp, sizeof(exp), "sys_get_be() failed"); } -extern void *common_setup(void); -ZTEST_SUITE(byteorder, NULL, common_setup, NULL, NULL, NULL); - /** * @} */ + + +extern void *common_setup(void); +ZTEST_SUITE(byteorder, NULL, common_setup, NULL, NULL, NULL); diff --git a/tests/kernel/common/src/clock.c b/tests/kernel/common/src/clock.c index 813a5c7c36e..090b2763fa8 100644 --- a/tests/kernel/common/src/clock.c +++ b/tests/kernel/common/src/clock.c @@ -29,7 +29,12 @@ static ZTEST_BMEM struct timer_data tdata; #define LESS_DURATION 70 /** - * @addtogroup kernel_common_tests + * @defgroup kernel_clock_tests Clock Operations + * @ingroup all_tests + * @{ + * @} + * + * @addtogroup kernel_clock_tests * @{ */ @@ -231,9 +236,9 @@ ZTEST(clock, test_ms_time_duration) k_timer_stop(&ktimer); } -extern void *common_setup(void); -ZTEST_SUITE(clock, NULL, common_setup, NULL, NULL, NULL); - /** * @} */ + + extern void *common_setup(void); + ZTEST_SUITE(clock, NULL, common_setup, NULL, NULL, NULL); diff --git a/tests/kernel/common/src/constructor.c b/tests/kernel/common/src/constructor.c index 6aca7f7cbe3..7a1bb054852 100644 --- a/tests/kernel/common/src/constructor.c +++ b/tests/kernel/common/src/constructor.c @@ -8,14 +8,15 @@ #include #include #include -/** - * @addtogroup kernel_common_tests - * @{ - */ /** - * @brief Test if constructors work + * @defgroup kernel_constructor_tests Constructors + * @ingroup all_tests + * @{ + * @} * + * @addtogroup kernel_constructor_tests + * @{ */ static int constructor_number; @@ -35,7 +36,10 @@ void __attribute__((__constructor__(1000))) __constructor_init_priority_1000(voi { constructor_values[constructor_number++] = 1000; } - +/** + * @brief Test if constructors work + * + */ ZTEST(constructor, test_constructor) { zassert_equal(constructor_number, 3, @@ -51,9 +55,9 @@ ZTEST(constructor, test_constructor) "constructor without priority not called last"); } -extern void *common_setup(void); -ZTEST_SUITE(constructor, NULL, common_setup, NULL, NULL, NULL); - /** * @} */ + + extern void *common_setup(void); + ZTEST_SUITE(constructor, NULL, common_setup, NULL, NULL, NULL); diff --git a/tests/kernel/common/src/errno.c b/tests/kernel/common/src/errno.c index 9155a5bd418..b185835b7d2 100644 --- a/tests/kernel/common/src/errno.c +++ b/tests/kernel/common/src/errno.c @@ -9,16 +9,7 @@ #include #include -/** - * @brief Test the thread context - * - * @defgroup kernel_threadcontext_tests Thread Context Tests - * - * @ingroup all_tests - * - * @{ - * @} - */ + #define N_THREADS 2 #define STACK_SIZE (384 + CONFIG_TEST_EXTRA_STACK_SIZE) @@ -59,12 +50,18 @@ static void errno_thread(void *_n, void *_my_errno, void *_unused) k_fifo_put(&fifo, &result[n]); } - +/** + * @defgroup kernel_errno_tests Error Number + * @ingroup all_tests + * @{ + * @} + * + * @addtogroup kernel_errno_tests + * @{ + */ /** * @brief Verify thread context * - * @ingroup kernel_threadcontext_tests - * * @details Check whether variable value per-thread are saved during * context switch */ @@ -140,8 +137,6 @@ void thread_entry_user(void *p1, void *p2, void *p3) * * @details Check whether a C standard errno can be stored successfully, * no matter it is using tls or not. - * - * @ingroup kernel_threadcontext_tests */ ZTEST_USER(common_errno, test_errno) { @@ -160,6 +155,8 @@ ZTEST_USER(common_errno, test_errno) k_thread_join(tid, K_FOREVER); } +/** + * @} + */ extern void *common_setup(void); - ZTEST_SUITE(common_errno, NULL, common_setup, NULL, NULL, NULL); diff --git a/tests/kernel/common/src/irq_offload.c b/tests/kernel/common/src/irq_offload.c index bffeb0dc94e..89815f70eb0 100644 --- a/tests/kernel/common/src/irq_offload.c +++ b/tests/kernel/common/src/irq_offload.c @@ -17,6 +17,16 @@ #include #include +/** + * @defgroup kernel_irq_offload_tests IRQ Offload + * @ingroup all_tests + * @{ + * @} + * + * @addtogroup kernel_irq_offload_tests + * @{ + */ + volatile uint32_t sentinel; #define SENTINEL_VALUE 0xDEADBEEF @@ -36,8 +46,6 @@ static void offload_function(const void *param) /** * @brief Verify thread context * - * @ingroup kernel_interrupt_tests - * * @details Check whether offloaded running function is in interrupt * context, on the IRQ stack or not. */ @@ -97,7 +105,8 @@ static void offload_thread_fn(void *p0, void *p1, void *p2) } } -/* Invoke irq_offload() from an interrupt and verify that the +/** + * @brief Invoke irq_offload from an interrupt and verify that the * resulting nested interrupt doesn't explode */ ZTEST(common_1cpu, test_nested_irq_offload) @@ -130,6 +139,8 @@ ZTEST(common_1cpu, test_nested_irq_offload) k_thread_abort(&offload_thread); } - +/** + * + */ extern void *common_setup(void); ZTEST_SUITE(irq_offload, NULL, common_setup, NULL, NULL, NULL); diff --git a/tests/kernel/common/src/printk.c b/tests/kernel/common/src/printk.c index 7c3a714817b..af0fd330d51 100644 --- a/tests/kernel/common/src/printk.c +++ b/tests/kernel/common/src/printk.c @@ -181,8 +181,14 @@ static int ram_console_out(int character) pos = (pos + 1) % BUF_SZ; return _old_char_out(character); } + /** - * @addtogroup kernel_common_tests + * @defgroup kernel_printk_tests Printk + * @ingroup all_tests + * @{ + * @} + * + * @addtogroup kernel_printk_tests * @{ */ @@ -253,9 +259,9 @@ ZTEST(printk, test_printk) zassert_str_equal(pk_console, expected, "snprintk failed"); } -extern void *common_setup(void); -ZTEST_SUITE(printk, NULL, common_setup, NULL, NULL, NULL); /** * @} */ +extern void *common_setup(void); +ZTEST_SUITE(printk, NULL, common_setup, NULL, NULL, NULL); diff --git a/tests/kernel/common/src/timeout_order.c b/tests/kernel/common/src/timeout_order.c index 582f659ae89..9dcd097a73f 100644 --- a/tests/kernel/common/src/timeout_order.c +++ b/tests/kernel/common/src/timeout_order.c @@ -36,7 +36,12 @@ static K_THREAD_STACK_ARRAY_DEFINE(stacks, NUM_TIMEOUTS, STACKSIZE); static struct k_thread threads[NUM_TIMEOUTS]; /** - * @addtogroup kernel_common_tests + * @defgroup kernel_timeout_tests Timeout Order + * @ingroup all_tests + * @{ + * @} + * + * @addtogroup kernel_timeout_tests * @{ */ @@ -88,10 +93,9 @@ ZTEST(common_1cpu, test_timeout_order) } } -extern void *common_setup(void); -ZTEST_SUITE(common_1cpu, NULL, common_setup, - ztest_simple_1cpu_before, ztest_simple_1cpu_after, NULL); - /** * @} */ +extern void *common_setup(void); +ZTEST_SUITE(common_1cpu, NULL, common_setup, + ztest_simple_1cpu_before, ztest_simple_1cpu_after, NULL);