components:libc:cplusplus:os/utest:Some comments have been initially added.

Some comments have been initially added as a bignner task.
components/libc/cplusplus/os/cxx_Semaphore.cpp
components/libc/cplusplus/os/cxx_Thread.cpp
components/libc/cplusplus/utest/tc_atomic.cpp
components/libc/cplusplus/utest/tc_smartptr.cpp
components/libc/cplusplus/utest/tc_thread.cpp

Signed-off-by:Liu Chengtao<[email protected]>

5 files changed, 132 insertions, 25 deletions

diff --git a/components/libc/cplusplus/os/cxx_Semaphore.cpp b/components/libc/cplusplus/os/cxx_Semaphore.cpp
index 672eeb04af..e0dbeb158a 100644
--- a/components/libc/cplusplus/os/cxx_Semaphore.cpp
+++ b/components/libc/cplusplus/os/cxx_Semaphore.cpp
@@ -11,11 +11,21 @@
 
 using namespace rtthread;
 
+/** 
+ * @brief Semaphore class constructor.
+ * @param name Semaphore name
+ * @param count Initial semaphore count
+ */
 Semaphore::Semaphore(const char *name, int32_t count)
 {
     rt_sem_init(&mID, name, count, RT_IPC_FLAG_FIFO);
 }
 
+/** 
+ * @brief Wait on the semaphore.
+ * @param millisec Timeout in milliseconds (-1 for infinite wait).
+ * @return true if the semaphore was successfully taken, false on timeout.
+ */
 bool Semaphore::wait(int32_t millisec)
 {
     rt_int32_t tick;
@@ -28,11 +38,17 @@ bool Semaphore::wait(int32_t millisec)
     return rt_sem_take(&mID, tick) == RT_EOK;
 }
 
+/** 
+ * @brief Release the semaphore.
+ */
 void Semaphore::release(void)
 {
     rt_sem_release(&mID);
 }
 
+/** 
+ * @brief Detach the semaphore when the object is destroyed.
+ */
 Semaphore::~Semaphore()
 {
     rt_sem_detach(&mID);
diff --git a/components/libc/cplusplus/os/cxx_Thread.cpp b/components/libc/cplusplus/os/cxx_Thread.cpp
index f3484bb1f4..dc444c255b 100644
--- a/components/libc/cplusplus/os/cxx_Thread.cpp
+++ b/components/libc/cplusplus/os/cxx_Thread.cpp
@@ -11,6 +11,13 @@
 
 using namespace rtthread;
 
+/** 
+ * @brief Thread class constructor with parameters for stack size, priority, tick, and name.
+ * @param stack_size Stack size in bytes
+ * @param priority Thread priority
+ * @param tick Time slice in ticks
+ * @param name Thread name
+ */
 Thread::Thread(rt_uint32_t stack_size,
                rt_uint8_t  priority,
                rt_uint32_t tick,
@@ -27,6 +34,15 @@ Thread::Thread(rt_uint32_t stack_size,
                                tick);
 }
 
+/** 
+ * @brief Thread class constructor with entry function and parameters.
+ * @param entry The entry function pointer for the thread.
+ * @param p The parameter to pass to the entry function.
+ * @param stack_size The size of the thread stack in bytes.
+ * @param priority The priority of the thread.
+ * @param tick The time slice (tick) for the thread.
+ * @param name The name of the thread.
+ */
 Thread::Thread(void (*entry)(void *p),
                void *p,
                rt_uint32_t stack_size,
@@ -45,12 +61,19 @@ Thread::Thread(void (*entry)(void *p),
                                tick);
 }
 
+/** 
+ * @brief Detach the event and delete the thread when the object is destroyed.
+ */
 Thread::~Thread()
 {
     rt_event_detach(&_event);
     rt_thread_delete(_thread);
 }
 
+/** 
+ * @brief Start the thread execution.
+ * @return true if the thread was successfully started.
+ */
 bool Thread::start()
 {
     if (rt_thread_startup(_thread) == RT_EOK)
@@ -61,6 +84,10 @@ bool Thread::start()
     return started;
 }
 
+/** 
+ * @brief Make the thread sleep for a specified duration.
+ * @param millisec Duration in milliseconds.
+ */
 void Thread::sleep(int32_t millisec)
 {
     rt_int32_t tick;
@@ -73,6 +100,9 @@ void Thread::sleep(int32_t millisec)
     rt_thread_delay(tick);
 }
 
+/** 
+ * @brief Function to run the thread's entry function.
+ */
 void Thread::func(Thread *pThis)
 {
     if (pThis->_entry != RT_NULL)
@@ -87,22 +117,34 @@ void Thread::func(Thread *pThis)
     rt_event_send(&pThis->_event, 1);
 }
 
+/** 
+ * @brief Default run function that can be overridden by subclasses.
+ */
 void Thread::run(void *parameter)
 {
     /* please overload this method */
 }
 
+/** 
+ * @brief Wait for the thread to complete with a timeout.
+ * @param millisec Timeout in milliseconds.
+ * @return RT_EOK if the thread completed within the timeout, error code otherwise.
+ */
 rt_err_t Thread::wait(int32_t millisec)
 {
     return join(millisec);
 }
 
+/** 
+ * @brief Join the thread with a timeout.
+ * @param millisec Timeout in milliseconds.
+ * @return RT_EOK if the thread completed within the timeout, error code otherwise.
+ */
 rt_err_t Thread::join(int32_t millisec)
 {
     if (started)
     {
         rt_int32_t tick;
-
         if (millisec < 0)
             tick = -1;
         else
@@ -114,4 +156,4 @@ rt_err_t Thread::join(int32_t millisec)
     {
         return -RT_ENOSYS;
     }
-}
+}
\ No newline at end of file
diff --git a/components/libc/cplusplus/utest/tc_atomic.cpp b/components/libc/cplusplus/utest/tc_atomic.cpp
index 8b5bdbd9ba..ae7c3b8841 100644
--- a/components/libc/cplusplus/utest/tc_atomic.cpp
+++ b/components/libc/cplusplus/utest/tc_atomic.cpp
@@ -20,7 +20,7 @@
  */
 static void test_atomic_load_store_int32(void)
 {
-    constexpr int        kRound = 10000000;
+    constexpr int kRound = 10000000;
     std::atomic<int32_t> thread_count(0);
     std::atomic<int32_t> count(100);
     uassert_int_equal(count.load(), 100);
@@ -56,7 +56,7 @@ static void test_atomic_load_store_int32(void)
  */
 static void test_atomic_load_store_int64(void)
 {
-    constexpr int        kRound = 10000000;
+    constexpr int kRound = 10000000;
     std::atomic<int64_t> thread_count(0);
     std::atomic<int64_t> count(100);
     uassert_int_equal(count.load(), 100);
@@ -112,7 +112,7 @@ static void test_atomic_basic_int32(void)
     val.fetch_and(14);
     uassert_int_equal(val.load(), 10);
 
-    val.fetch_or(11); //1010
+    val.fetch_or(11); /* 1010 */
     uassert_int_equal(val.load(), 11);
 
     val.fetch_xor(4);
@@ -121,9 +121,9 @@ static void test_atomic_basic_int32(void)
     val.exchange(1);
     uassert_int_equal(val.load(), 1);
 
-    int32_t x         = 2;
-    int32_t y         = 3;
-    bool    exchanged = val.compare_exchange_strong(x, y);
+    int32_t x = 2;
+    int32_t y = 3;
+    bool exchanged = val.compare_exchange_strong(x, y);
     uassert_false(exchanged);
     uassert_int_equal(val.load(), 1);
     uassert_int_equal(x, 1);
@@ -159,7 +159,7 @@ static void test_atomic_basic_int64(void)
     val.fetch_and(14);
     uassert_int_equal(val.load(), 10);
 
-    val.fetch_or(11); //1010
+    val.fetch_or(11); /* 1010 */
     uassert_int_equal(val.load(), 11);
 
     val.fetch_xor(4);
@@ -168,9 +168,9 @@ static void test_atomic_basic_int64(void)
     val.exchange(1);
     uassert_int_equal(val.load(), 1);
 
-    int64_t x         = 2;
-    int64_t y         = 3;
-    bool    exchanged = val.compare_exchange_strong(x, y);
+    int64_t x = 2;
+    int64_t y = 3;
+    bool exchanged = val.compare_exchange_strong(x, y);
     uassert_false(exchanged);
     uassert_int_equal(val.load(), 1);
     uassert_int_equal(x, 1);
@@ -191,7 +191,7 @@ static void test_atomic_bool(void)
     flag.exchange(false);
     uassert_false(flag.load());
     bool expected = false;
-    bool desired  = true;
+    bool desired = true;
     uassert_true(flag.compare_exchange_strong(expected, desired));
     uassert_true(flag.load());
 }
@@ -201,7 +201,7 @@ static void test_atomic_bool(void)
  */
 static void test_atomic_pointer(void)
 {
-    int                a = 1, b = 2;
+    int a = 1, b = 2;
     std::atomic<int *> ptr(&a);
     ptr.store(&b);
     uassert_int_equal(*ptr.load(), 2);
@@ -217,7 +217,7 @@ static void test_memory_order(void)
 {
     std::atomic<int> x(0);
     std::atomic<int> y(0);
-    // Simple test for memory order
+    /* Simple test for memory order */
     x.store(1, std::memory_order_release);
     y.store(2, std::memory_order_release);
     uassert_int_equal(x.load(std::memory_order_acquire), 1);
@@ -230,25 +230,36 @@ static void test_memory_order(void)
 static void test_compare_exchange_weak(void)
 {
     std::atomic<int> val(1);
-    int              expected = 1;
-    int              desired  = 2;
+    int expected = 1;
+    int desired = 2;
     while (!val.compare_exchange_weak(expected, desired))
     {
-        expected = 1; // reset
+        /* Reset */
+        expected = 1; 
     }
     uassert_int_equal(val.load(), 2);
 }
-
+/**
+ * @brief Test case initialization function.
+ * @return RT_EOK on success.
+ */
 static rt_err_t utest_tc_init(void)
 {
     return RT_EOK;
 }
 
+/**
+ * @brief Test case cleanup function.
+ * @return RT_EOK on success.
+ */
 static rt_err_t utest_tc_cleanup(void)
 {
     return RT_EOK;
 }
 
+/**
+ * @brief Main test case function that runs the test.
+ */
 static void testcase(void)
 {
     /* Test load and store operations for int32_t atomic variables in multi-threaded environment */
@@ -268,4 +279,6 @@ static void testcase(void)
     /* Test compare_exchange_weak operation */
     UTEST_UNIT_RUN(test_compare_exchange_weak);
 }
-UTEST_TC_EXPORT(testcase, "components.libc.cpp.atomic_tc", utest_tc_init, utest_tc_cleanup, 10);
+
+/* Export the test case with initialization and cleanup functions and a timeout of 10 ticks. */
+UTEST_TC_EXPORT(testcase, "components.libc.cpp.atomic_tc", utest_tc_init, utest_tc_cleanup, 10);
\ No newline at end of file
diff --git a/components/libc/cplusplus/utest/tc_smartptr.cpp b/components/libc/cplusplus/utest/tc_smartptr.cpp
index 1a9fa7eb11..c75149c850 100644
--- a/components/libc/cplusplus/utest/tc_smartptr.cpp
+++ b/components/libc/cplusplus/utest/tc_smartptr.cpp
@@ -35,16 +35,27 @@ static void test_shared_ptr(void)
     uassert_int_equal(p1.use_count(), 2);
 }
 
+/**
+ * @brief Test case initialization function.
+ * @return RT_EOK on success.
+ */
 static rt_err_t utest_tc_init(void)
 {
     return RT_EOK;
 }
 
+/**
+ * @brief Test case cleanup function.
+ * @return RT_EOK on success.
+ */
 static rt_err_t utest_tc_cleanup(void)
 {
     return RT_EOK;
 }
 
+/**
+ * @brief Main test case function that runs the test.
+ */
 static void testcase(void)
 {
     /* Test unique_ptr basic operations */
@@ -52,4 +63,6 @@ static void testcase(void)
     /* Test shared_ptr basic operations */
     UTEST_UNIT_RUN(test_shared_ptr);
 }
-UTEST_TC_EXPORT(testcase, "components.libc.cpp.smartptr_tc", utest_tc_init, utest_tc_cleanup, 10);
+
+/* Export the test case with initialization and cleanup functions and a timeout of 10 ticks. */
+UTEST_TC_EXPORT(testcase, "components.libc.cpp.smartptr_tc", utest_tc_init, utest_tc_cleanup, 10);
\ No newline at end of file
diff --git a/components/libc/cplusplus/utest/tc_thread.cpp b/components/libc/cplusplus/utest/tc_thread.cpp
index c60a9ab602..2f81da5c41 100644
--- a/components/libc/cplusplus/utest/tc_thread.cpp
+++ b/components/libc/cplusplus/utest/tc_thread.cpp
@@ -12,25 +12,34 @@
 #include "utest.h"
 #include <thread>
 
+
+/**
+ * @brief Function to test thread functionality.
+ */
 static void test_thread(void)
 {
     int count = 0;
-    auto func = [&]() mutable
-    {
+
+    /* Lambda function to increment the count. */
+    auto func = [&]() mutable {
         for (int i = 0; i < 100; ++i)
         {
             ++count;
         }
     };
 
+    /* Create and run a thread executing the lambda function. */
     std::thread t1(func);
+    /* Wait for the thread to finish execution. */
     t1.join();
 
+    /* Verify if the count is as expected after the first thread execution. */
     if (count != 100)
     {
         uassert_false(1);
     }
 
+    /* Create and run another thread executing the same lambda function. */
     std::thread t2(func);
     t2.join();
 
@@ -39,21 +48,35 @@ static void test_thread(void)
         uassert_false(1);
     }
 
+    /* If both assertions passed, the test is successful. */
     uassert_true(1);
 }
 
+
+/**
+ * @brief Test case initialization function.
+ * @return RT_EOK on success.
+ */
 static rt_err_t utest_tc_init(void)
 {
     return RT_EOK;
 }
-
+/**
+ * @brief Test case cleanup function.
+ * @return RT_EOK on success.
+ */
 static rt_err_t utest_tc_cleanup(void)
 {
     return RT_EOK;
 }
 
+/**
+ * @brief Main test case function that runs the test.
+ */
 static void testcase(void)
 {
     UTEST_UNIT_RUN(test_thread);
 }
-UTEST_TC_EXPORT(testcase, "components.libc.cpp.thread_tc", utest_tc_init, utest_tc_cleanup, 10);
+
+/* Export the test case with initialization and cleanup functions and a timeout of 10 ticks. */
+UTEST_TC_EXPORT(testcase, "components.libc.cpp.thread_tc", utest_tc_init, utest_tc_cleanup, 10);
\ No newline at end of file