tests: kernel: threads: improve doxygen comments, layout

Fix grouping and general doxygen fixups.

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

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

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

@@ -23,7 +23,7 @@ struct isr_arg {
 static struct isr_arg prio_args;
 
 /**
- * @brief Test ISR used to change a thread's priority
+ * @brief Test changing a thread's priority from an ISR
  */
 static void test_isr(const void *arg)
 {
@@ -33,9 +33,7 @@ static void test_isr(const void *arg)
 }
 
 /**
- *
+ * @brief Test thread behavior when its priority is changed
- * @brief thread2 portion to test setting the priority
- *
  */
 void thread2_set_prio_test(void *p1, void *p2, void *p3)
 {
@@ -61,7 +59,11 @@ void thread2_set_prio_test(void *p1, void *p2, void *p3)
 
 /**
  * @ingroup kernel_thread_tests
- * @brief Test the k_thread_priority_set() API
+ * @brief Test setting and verifying thread priorities
+ *
+ * @details This test creates a thread with a lower priority than the
+ * current thread. It then sets the priority of the thread to a
+ * higher value, and checks that the priority has been set correctly.
  *
  * @see k_thread_priority_set(), k_thread_priority_get()
  */
@@ -74,61 +76,64 @@ ZTEST(threads_lifecycle, test_threads_priority_set)
 	k_thread_priority_set(k_current_get(), prio + 2);
 	rv = k_thread_priority_get(k_current_get());
 	zassert_equal(rv, prio + 2,
-		      "Expected priority to be changed to %d, not %d\n",
+			"Expected priority to be changed to %d, not %d\n",
-		      prio + 2, rv);
+			prio + 2, rv);
 
 	/* Raise the priority of the current thread (thread1) */
 	k_thread_priority_set(k_current_get(), prio - 2);
 	rv = k_thread_priority_get(k_current_get());
 	zassert_equal(rv, prio - 2,
-		      "Expected priority to be changed to %d, not %d\n",
+			"Expected priority to be changed to %d, not %d\n",
-		      prio - 2, rv);
+			prio - 2, rv);
 
 	/* Restore the priority of the current thread (thread1) */
 	k_thread_priority_set(k_current_get(), prio);
 	rv = k_thread_priority_get(k_current_get());
 	zassert_equal(rv, prio,
-		      "Expected priority to be changed to %d, not %d\n",
+			"Expected priority to be changed to %d, not %d\n",
-		      prio, rv);
+			prio, rv);
 
 	/* create thread with lower priority */
 	int thread2_prio = prio + 1;
 
 	k_tid_t thread2_id = k_thread_create(&tdata, tstack, STACK_SIZE,
-					     thread2_set_prio_test,
+			thread2_set_prio_test,
-					     NULL, NULL, NULL, thread2_prio, 0,
+			NULL, NULL, NULL, thread2_prio, 0,
-					     K_NO_WAIT);
+			K_NO_WAIT);
 
 	/* Lower the priority of thread2 */
 	k_thread_priority_set(thread2_id, thread2_prio + 2);
 	k_sem_give(&sem_thread2);
 	k_sem_take(&sem_thread1, K_FOREVER);
 	zassert_equal(thread2_data, thread2_prio + 2,
-		      "Expected priority to be changed to %d, not %d\n",
+			"Expected priority to be changed to %d, not %d\n",
-		      thread2_prio + 2, thread2_data);
+			thread2_prio + 2, thread2_data);
 
 	/* Raise the priority of thread2 */
 	k_thread_priority_set(thread2_id, thread2_prio - 2);
 	k_sem_give(&sem_thread2);
 	k_sem_take(&sem_thread1, K_FOREVER);
 	zassert_equal(thread2_data, thread2_prio - 2,
-		      "Expected priority to be changed to %d, not %d\n",
+			"Expected priority to be changed to %d, not %d\n",
-		      thread2_prio - 2, thread2_data);
+			thread2_prio - 2, thread2_data);
 
 	/* Restore the priority of thread2 */
 	k_thread_priority_set(thread2_id, thread2_prio);
 	k_sem_give(&sem_thread2);
 	k_sem_take(&sem_thread1, K_FOREVER);
 	zassert_equal(thread2_data, thread2_prio,
-		      "Expected priority to be changed to %d, not %d\n",
+			"Expected priority to be changed to %d, not %d\n",
-		      thread2_prio, thread2_data);
+			thread2_prio, thread2_data);
 
 	k_thread_join(thread2_id, K_FOREVER);
 }
 
 /**
  * @ingroup kernel_thread_tests
- * @brief Test the k_thread_priority_set() API from an ISR
+ * @brief Test changing thread priorities from an ISR
+ *
+ * @details This test verifies that thread priorities can be changed
+ * correctly when invoked from an interrupt service routine (ISR).
  *
  * @see k_thread_priority_set(), k_thread_priority_get()
  */
@@ -143,32 +148,32 @@ ZTEST(threads_lifecycle, test_isr_threads_priority_set_)
 	irq_offload(test_isr, &prio_args);
 	rv = k_thread_priority_get(k_current_get());
 	zassert_equal(rv, prio + 2,
-		      "Expected priority to be changed to %d, not %d\n",
+			"Expected priority to be changed to %d, not %d\n",
-		      prio + 2, rv);
+			prio + 2, rv);
 
 	/* Raise the priority of the current thread (thread1) */
 	prio_args.prio = prio - 2;
 	irq_offload(test_isr, &prio_args);
 	rv = k_thread_priority_get(k_current_get());
 	zassert_equal(rv, prio - 2,
-		      "Expected priority to be changed to %d, not %d\n",
+			"Expected priority to be changed to %d, not %d\n",
-		      prio - 2, rv);
+			prio - 2, rv);
 
 	/* Restore the priority of the current thread (thread1) */
 	prio_args.prio = prio;
 	irq_offload(test_isr, &prio_args);
 	rv = k_thread_priority_get(k_current_get());
 	zassert_equal(rv, prio,
-		      "Expected priority to be changed to %d, not %d\n",
+			"Expected priority to be changed to %d, not %d\n",
-		      prio, rv);
+			prio, rv);
 
 	/* create thread with lower priority */
 	int thread2_prio = prio + 1;
 
 	k_tid_t thread2_id = k_thread_create(&tdata, tstack, STACK_SIZE,
-					     thread2_set_prio_test,
+			thread2_set_prio_test,
-					     NULL, NULL, NULL, thread2_prio, 0,
+			NULL, NULL, NULL, thread2_prio, 0,
-					     K_NO_WAIT);
+			K_NO_WAIT);
 
 	/* Lower the priority of thread2 */
 	prio_args.thread = thread2_id;
@@ -177,8 +182,8 @@ ZTEST(threads_lifecycle, test_isr_threads_priority_set_)
 	k_sem_give(&sem_thread2);
 	k_sem_take(&sem_thread1, K_FOREVER);
 	zassert_equal(thread2_data, thread2_prio + 2,
-		      "Expected priority to be changed to %d, not %d\n",
+			"Expected priority to be changed to %d, not %d\n",
-		      thread2_prio + 2, thread2_data);
+			thread2_prio + 2, thread2_data);
 
 	/* Raise the priority of thread2 */
 	prio_args.prio = thread2_prio - 2;
@@ -186,8 +191,8 @@ ZTEST(threads_lifecycle, test_isr_threads_priority_set_)
 	k_sem_give(&sem_thread2);
 	k_sem_take(&sem_thread1, K_FOREVER);
 	zassert_equal(thread2_data, thread2_prio - 2,
-		      "Expected priority to be changed to %d, not %d\n",
+			"Expected priority to be changed to %d, not %d\n",
-		      thread2_prio - 2, thread2_data);
+			thread2_prio - 2, thread2_data);
 
 	/* Restore the priority of thread2 */
 	prio_args.prio = thread2_prio;
@@ -195,7 +200,7 @@ ZTEST(threads_lifecycle, test_isr_threads_priority_set_)
 	k_sem_give(&sem_thread2);
 	k_sem_take(&sem_thread1, K_FOREVER);
 	zassert_equal(thread2_data, thread2_prio,
-		      "Expected priority to be changed to %d, not %d\n",
+			"Expected priority to be changed to %d, not %d\n",
-		      thread2_prio, thread2_data);
+			thread2_prio, thread2_data);
 	k_thread_join(thread2_id, K_FOREVER);
 }

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

@@ -129,7 +129,7 @@ ZTEST(threads_lifecycle, test_threads_spawn_forever)
 
 /**
  * @ingroup kernel_thread_tests
- * @brief Validate behavior of multiple calls to k_thread_start()
+ * @brief Validate behavior of multiple calls to k_thread_start
  *
  * @details Call k_thread_start() on an already terminated thread
  *

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

@@ -86,7 +86,7 @@ void suspend_myself(void *arg0, void *arg1, void *arg2)
 /**
  * @ingroup kernel_thread_tests
  *
- * @brief Check that k_thread_suspend() is a schedule point when
+ * @brief Check that suspending a thread is a schedule point when
  * called on the current thread.
  */
 ZTEST(threads_lifecycle, test_threads_suspend)
@@ -121,7 +121,7 @@ void sleep_suspended(void *arg0, void *arg1, void *arg2)
 
 /**
  * @ingroup kernel_thread_tests
- * @brief Check that k_thread_suspend() cancels a preexisting thread timeout
+ * @brief Check that suspending a thread cancels a preexisting thread timeout
  *
  * @details Suspended threads should not wake up unexpectedly if they
  * happened to have been sleeping when suspended.
@@ -149,7 +149,7 @@ ZTEST(threads_lifecycle, test_threads_suspend_timeout)
 
 /**
  * @ingroup kernel_thread_tests
- * @brief Check resume an unsuspend thread
+ * @brief Check resuming a thread that is not suspended
  *
  * @details Use k_thread_state_str() to get thread state.
  * Resume an unsuspend thread will not change the thread state.