docs(utest):Add standardized documentation for IPC Completion Test Test

Signed-off-by: ChuanN-sudo <fjchuanil@gmail.com>

Author: ChuanN-sudo

components/drivers/ipc/utest/completion_tc.c

@@ -6,23 +6,40 @@
  * Change Logs:
  * Date           Author       Notes
  * 2024-04-30     Shell        init ver.
+ * 2025-11-16     ChuanN-sudo  add standardized utest documentation block
  */
 
 /**
- * Test Case for rt_completion API
+ * Test Case Name: IPC Completion Basic Test
  *
- * The test simulates a producer-consumer interaction where a producer thread
- * generates data, and a consumer thread consumes the data after waiting for its
- * availability using rt_completion synchronization primitives.
+ * Test Objectives:
+ * - Validate rt_completion initialization, wait, and wake-up mechanisms.
+ * - Verify thread synchronization in producer-consumer model.
+ * - Test core APIs: rt_completion_init(), rt_completion_wait_flags(), rt_completion_wakeup()
  *
- * Test Criteria:
- * - The producer should correctly increment the test data and signal
- *   completion.
- * - The consumer should correctly wait for data update, consume it, and signal
- *   completion.
+ * Test Scenarios:
+ * - Producer thread generates incrementing data and notifies consumer.
+ * - Consumer thread waits for data updates and validates integrity.
+ * - Random delays simulate race conditions in synchronization.
+ *
+ * Verification Metrics:
+ * - The producer should correctly increment the test data and signal completion.
+ * - The consumer should correctly wait for data update, consume it, and signal completion.
  * - Data integrity should be maintained between producer and consumer.
  * - Synchronization is properly done so both can see consistent data.
  * - Random latency is introduced to simulate racing scenarios.
+ *
+ * Dependencies:
+ * - Hardware requirements: QEMU emulator or any hardware platform that supports RT-Thread,
+ * - Software configuration:
+ *     - RT_USING_UTEST must be enabled (select "RT-Thread Utestcases" in menuconfig).
+ *     - RT_UTEST_COMPLETION must be enabled (enable via: RT-Thread Utestcases -> Kernel Components -> Drivers -> IPC Test -> IPC Completion Test).
+ * - Environmental Assumptions: System scheduler working normally.
+ *
+ * Expected Results:
+ * - Progress logs: "[ INFO ] components.drivers.ipc.rt_completion_basic: Summary:...Test times:..."
+ * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.ipc.rt_completion_basic)"
+ * - No assertions triggered.
  */
 
 #define TEST_LATENCY_TICK (1)
@@ -76,7 +93,8 @@ static void wait_safely(struct rt_completion *completion)
         {
             break;
         }
-    } while (1);
+    }
+    while (1);
 }
 
 static void producer_thread_entry(void *parameter)
@@ -108,7 +126,8 @@ static void _wait_until_edge(void)
     do
     {
         current = rt_tick_get();
-    } while (current == entry_level);
+    }
+    while (current == entry_level);
 
     /* give a random latency for test */
     random_latency = rand();

components/drivers/ipc/utest/completion_timeout_tc.c

@@ -6,29 +6,43 @@
  * Change Logs:
  * Date           Author       Notes
  * 2024-04-30     Shell        init ver.
+ * 2025-11-16     ChuanN-sudo  add standardized utest documentation block
  */
 
 /**
- * Test Case for rt_completion API
+ * Test Case Name: IPC Completion Timeout Test
  *
- * The test simulates a producer-consumer interaction where a producer thread
- * generates data, and a consumer thread consumes the data after waiting for its
- * availability using rt_completion synchronization primitives.
+ * Test Objectives:
+ * - VaValidate rt_completion initialization, wait with timeout, and wake-up mechanisms.
+ * - Verify thread synchronization resilience in producer-consumer model under timing constraints.
+ * - Test core APIs: rt_completion_init(), rt_completion_wait_flags(), rt_completion_wakeup()
+ * - Verify proper handling of timeout and interrupt scenarios during synchronization.
  *
- * Test Criteria:
+ * Test Scenarios:
+ * - Producer thread generates incrementing data with small delays between productions.
+ * - Consumer thread waits for data with timeout flags (RT_INTERRUPTIBLE) to simulate real-world interruptions.
+ * - Test deliberately introduces random thread yields to simulate scheduling variations.
+ * - Producer-consumer synchronization loop runs for extended duration to expose timing issues.
+ * - System handles asynchronous interruptions during wait operations.
+ *
+ * Verification Metrics:
  * - The producer produces data correctly and notifies the consumer thread.
- * - The consumer receives data correctly and acknowledges receipt to the
- *   producer.
+ * - The consumer receives data correctly and acknowledges receipt to the producer.
  * - The producer and consumer threads synchronize their operations effectively.
- * - Verify the correctness of data production and consumption between producer
- *   and consumer threads.
- * - The asynchronous woken of consumer thread was handled properly so the
- *   consumer don't lose woken from producer.
+ * - Verify the correctness of data production and consumption between producer and consumer threads.
+ * - The asynchronous woken of consumer thread was handled properly so the consumer don't lose woken from producer.
+ *
+ * Dependencies:
+ * - Hardware requirements: QEMU emulator or any hardware platform that supports RT-Thread.
+ * - Software configuration:
+ *     - RT_USING_UTEST must be enabled (select "RT-Thread Utestcases" in menuconfig).
+ *     - RT_UTEST_COMPLETION must be enabled (enable via: RT-Thread Utestcases -> Kernel Components -> Drivers -> IPC Test -> IPC Completion Test).
+ * - Environmental Assumptions: System clock interrupts and scheduler working normally
  *
- * Test APIs:
- * - rt_completion_init()
- * - rt_completion_wakeup()
- * - rt_completion_wait_flags()
+ * Expected Results:
+ * - Progress logs: "[ INFO ] components.drivers.ipc.rt_completion_timeout: Summary:...Test times:...Async interruption count:...".
+ * - Final output: "[ PASSED ] [ result ] testcase (components.drivers.ipc.rt_completion_timeout)".
+ * - No assertions triggered.
  */
 
 #define TEST_LATENCY_TICK (1)
@@ -100,7 +114,8 @@ static void wait_safely(struct rt_completion *completion)
         {
             break;
         }
-    } while (try_times--);
+    }
+    while (try_times--);
 
     if (error != RT_EOK)
     {