tests: kernel: threads: improve doxygen comments, layout

Fix grouping and general doxygen fixups.

Signed-off-by: Anas Nashif <[email protected]>

Author: nashif

tests/kernel/threads/thread_apis/src/main.c

@@ -78,7 +78,7 @@ static void customdata_entry(void *p1, void *p2, void *p3)
 
 /**
  * @ingroup kernel_thread_tests
- * @brief test thread custom data get/set from coop thread
+ * @brief Test thread custom data get/set from coop thread
  *
  * @see k_thread_custom_data_get(), k_thread_custom_data_set()
  */
@@ -101,7 +101,7 @@ static void thread_name_entry(void *p1, void *p2, void *p3)
 
 /**
  * @ingroup kernel_thread_tests
- * @brief test thread name get/set from supervisor thread
+ * @brief Test thread name get/set from supervisor thread
  * @see k_thread_name_get(), k_thread_name_copy(), k_thread_name_set()
  */
 ZTEST(threads_lifecycle, test_thread_name_get_set)
@@ -142,7 +142,7 @@ struct k_sem sem;
 
 /**
  * @ingroup kernel_thread_tests
- * @brief test thread name get/set from user thread
+ * @brief Test thread name get/set from user thread
  * @see k_thread_name_copy(), k_thread_name_set()
  */
 ZTEST_USER(threads_lifecycle, test_thread_name_user_get_set)
@@ -211,7 +211,7 @@ ZTEST_USER(threads_lifecycle, test_thread_name_user_get_set)
 
 /**
  * @ingroup kernel_thread_tests
- * @brief test thread custom data get/set from preempt thread
+ * @brief Test thread custom data get/set from preempt thread
  * @see k_thread_custom_data_get(), k_thread_custom_data_set()
  */
 ZTEST_USER(threads_lifecycle_1cpu, test_customdata_get_set_preempt)
@@ -243,7 +243,7 @@ static void umode_entry(void *thread_id, void *p2, void *p3)
 
 /**
  * @ingroup kernel_thread_tests
- * @brief Test k_thread_user_mode_enter() to cover when userspace
+ * @brief Test k_thread_user_mode_enter to cover when userspace
  * is not supported/enabled
  * @see k_thread_user_mode_enter()
  */
@@ -392,6 +392,11 @@ static inline int join_scenario(enum control_method m)
 	return join_scenario_interval(m, NULL);
 }
 
+/**
+ * @ingroup kernel_thread_tests
+ * @brief Test thread join
+ *
+ */
 ZTEST_USER(threads_lifecycle, test_thread_join)
 {
 	int64_t interval;
@@ -415,6 +420,13 @@ ZTEST_USER(threads_lifecycle, test_thread_join)
 
 }
 
+/**
+ * @ingroup kernel_thread_tests
+ * @brief Test thread join from ISR
+ *
+ * @see k_thread_join()
+ * @see k_thread_abort()
+ */
 ZTEST(threads_lifecycle, test_thread_join_isr)
 {
 	zassert_equal(join_scenario(ISR_RUNNING), -EBUSY, "failed isr running");
@@ -447,6 +459,21 @@ static void deadlock2_entry(void *p1, void *p2, void *p3)
 	zassert_equal(ret, 0, "couldn't join deadlock2_thread");
 }
 
+
+
+/**
+ * @brief Test case for thread join deadlock scenarios.
+ *
+ * This test verifies the behavior of the `k_thread_join` API in scenarios
+ * that could lead to deadlocks. It includes the following checks:
+ *
+ * - Ensures that a thread cannot join itself, which would result in a
+ *   self-deadlock. The API should return `-EDEADLK` in this case.
+ * - Creates two threads (`deadlock1_thread` and `deadlock2_thread`) and
+ *   verifies that they can be joined successfully without causing a deadlock.
+ *
+ * @ingroup kernel_thread_tests
+ */
 ZTEST_USER(threads_lifecycle, test_thread_join_deadlock)
 {
 	/* Deadlock scenarios */
@@ -476,6 +503,11 @@ static void user_start_thread(void *p1, void *p2, void *p3)
 {
 	/* do nothing */
 }
+/**
+ * @brief Test case for verifying thread timeout expiration and remaining time.
+ *
+ * @ingroup kernel_thread_tests
+ */
 
 ZTEST_USER(threads_lifecycle, test_thread_timeout_remaining_expires)
 {
@@ -528,10 +560,16 @@ static void foreach_callback(const struct k_thread *thread, void *user_data)
 		stats.execution_cycles;
 }
 
-/* This case accumulates every thread's execution_cycles first, then
+/**
+ * @brief Test case for thread runtime statistics retrieval in Zephyr kernel
+ *
+ * This case accumulates every thread's execution_cycles first, then
  * get the total execution_cycles from a global
  * k_thread_runtime_stats_t to see that all time is reflected in the
  * total.
+ *
+ * @ingroup kernel_thread_tests
+ * @see k_thread_runtime_stats_get()
  */
 ZTEST(threads_lifecycle, test_thread_runtime_stats_get)
 {
@@ -551,6 +589,13 @@ ZTEST(threads_lifecycle, test_thread_runtime_stats_get)
 	zassert_true(stats.execution_cycles <= stats_all.execution_cycles);
 }
 
+
+/**
+ * @brief Test the behavior of k_busy_wait with thread runtime statistics.
+ *
+ * This test verifies the accuracy of the `k_busy_wait` function by checking
+ * the thread's execution cycle statistics before and after calling the function.
+ */
 ZTEST(threads_lifecycle, test_k_busy_wait)
 {
 	uint64_t cycles, dt;
@@ -589,6 +634,12 @@ static void tp_entry(void *p1, void *p2, void *p3)
 	tp = 100;
 }
 
+/**
+ * @brief Test the behavior of k_busy_wait with thread runtime statistics
+ *        in user mode.
+ *
+ * @ingroup kernel_thread_tests
+ */
 ZTEST_USER(threads_lifecycle_1cpu, test_k_busy_wait_user)
 {
 
@@ -624,9 +675,14 @@ static int small_stack(size_t *space)
 	return k_thread_stack_space_get(k_current_get(), space);
 }
 
-/* test k_thread_stack_sapce_get(), unused stack space in large_stack_space()
+/**
+ * @brief Test k_thread_stack_sapce_get
+ *
+ * Test k_thread_stack_sapce_get unused stack space in large_stack_space()
  * is smaller than that in small_stack() because the former function has a
  * large local variable
+ *
+ * @ingroup kernel_thread_tests
  */
 ZTEST_USER(threads_lifecycle, test_k_thread_stack_space_get_user)
 {

tests/kernel/threads/thread_apis/src/test_essential_thread.c

@@ -114,6 +114,16 @@ ZTEST(threads_lifecycle, test_essential_thread_abort)
 	zassert_true(fatal_error_signaled, "fatal error was not signaled");
 }
 
+/**
+ * @brief Abort an essential thread from itself
+ *
+ * @details The kernel shall raise a fatal system error if an essential thread
+ *          aborts, implement k_sys_fatal_error_handler to handle this error.
+ *
+ * @ingroup kernel_thread_tests
+ *
+ * @see #K_ESSENTIAL(x)
+ */
 ZTEST(threads_lifecycle, test_essential_thread_abort_self)
 {
 	/* This test case needs to be able to handle a k_panic() call

tests/kernel/threads/thread_apis/src/test_threads_cancel_abort.c

@@ -32,7 +32,7 @@ static void thread_entry_abort(void *p1, void *p2, void *p3)
 }
 /**
  * @ingroup kernel_thread_tests
- * @brief Validate k_thread_abort() when called by current thread
+ * @brief Validate aborting a thread when called by current thread
  *
  * @details Create a user thread and let the thread execute.
  * Then call k_thread_abort() and check if the thread is terminated.
@@ -52,7 +52,7 @@ ZTEST_USER(threads_lifecycle, test_threads_abort_self)
 
 /**
  * @ingroup kernel_thread_tests
- * @brief Validate k_thread_abort() when called by other thread
+ * @brief Validate aborting a thread when called by other thread
  *
  * @details Create a user thread and abort the thread before its
  * execution. Create a another user thread and abort the thread
@@ -85,7 +85,7 @@ ZTEST_USER(threads_lifecycle, test_threads_abort_others)
 
 /**
  * @ingroup kernel_thread_tests
- * @brief Test abort on a terminated thread
+ * @brief Test abort on an already terminated thread
  *
  * @see k_thread_abort()
  */

tests/kernel/threads/thread_apis/src/test_threads_cpu_mask.c

@@ -22,6 +22,19 @@ void child_fn(void *a, void *b, void *c)
 	child_has_run = true;
 }
 
+
+/**
+ * @brief Test the CPU mask APIs for thread lifecycle management
+ *
+ * This test verifies the behavior of the CPU mask APIs in the Zephyr kernel
+ * for thread lifecycle management. It ensures that the APIs behave as expected
+ * when operating on both running and non-running threads.
+ *
+ * @note This test is only executed if `CONFIG_SCHED_CPU_MASK` is enabled.
+ *       Otherwise, the test is skipped.
+ *
+ * @ingroup kernel_thread_tests
+ */
 ZTEST(threads_lifecycle_1cpu, test_threads_cpu_mask)
 {
 #ifdef CONFIG_SCHED_CPU_MASK