Merge pull request #4859 from KyleChenjh/ipc_comment

[comment] Optimize the comment for ipc

1 files changed, 848 insertions, 231 deletions

diff --git a/src/ipc.c b/src/ipc.c
index 6bc9c079b9..8acfd831d7 100755
--- a/src/ipc.c
+++ b/src/ipc.c
@@ -57,11 +57,16 @@ extern void (*rt_object_put_hook)(struct rt_object *object);
 /**@{*/
 
 /**
- * This function will initialize an IPC object
+ * @brief    This function will initialize an IPC object, such as semaphore, mutex, messagequeue and mailbox.
  *
- * @param ipc the IPC object
+ * @note     Executing this function will complete an initialization of the suspend thread list of the ipc object.
  *
- * @return the operation status, RT_EOK on successful
+ * @param    ipc is a pointer to the IPC object.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the initialization is successful.
+ *           When the return value is any other values, it means the initialization failed.
+ *
+ * @warning  This function can be called from all IPC initialization and creation.
  */
 rt_inline rt_err_t rt_ipc_object_init(struct rt_ipc_object *ipc)
 {
@@ -71,16 +76,35 @@ rt_inline rt_err_t rt_ipc_object_init(struct rt_ipc_object *ipc)
     return RT_EOK;
 }
 
+
 /**
- * This function will suspend a thread to a specified list. IPC object or some
- * double-queue object (mailbox etc.) contains this kind of list.
+ * @brief    This function will suspend a thread to a IPC object list.
+ *
+ * @param    list is a pointer to a suspended thread list of the IPC object.
+ *
+ * @param    thread is a pointer to the thread object to be suspended.
+ *
+ * @param    flag is a flag for the thread object to be suspended. It determines how the thread is suspended.
+ *           The flag can be ONE of the following values:
+ *
+ *               RT_IPC_FLAG_PRIO          The pending threads will queue in order of priority.
+ *
+ *               RT_IPC_FLAG_FIFO          The pending threads will queue in the first-in-first-out method
+ *                                         (also known as first-come-first-served (FCFS) scheduling strategy).
+ *
+ *               NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to use
+ *               RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about
+ *               the first-in-first-out principle, and you clearly understand that all threads involved in
+ *               this semaphore will become non-real-time threads.
  *
- * @param list the IPC suspended thread list
- * @param thread the thread object to be suspended
- * @param flag the IPC object flag,
- *        which shall be RT_IPC_FLAG_FIFO/RT_IPC_FLAG_PRIO.
+ * @return   Return the operation status. When the return value is RT_EOK, the function is successfully executed.
+ *           When the return value is any other values, it means the initialization failed.
  *
- * @return the operation status, RT_EOK on successful
+ * @warning  This function can ONLY be called in the thread context, you can use RT_DEBUG_IN_THREAD_CONTEXT to
+ *           check the context.
+ *           In addition, this function is generally called by the following functions:
+ *           rt_sem_take(),  rt_mutex_take(),  rt_event_recv(),   rt_mb_send_wait(),
+ *           rt_mb_recv(),   rt_mq_recv(),     rt_mq_send_wait()
  */
 rt_inline rt_err_t rt_ipc_list_suspend(rt_list_t        *list,
                                        struct rt_thread *thread,
@@ -131,14 +155,25 @@ rt_inline rt_err_t rt_ipc_list_suspend(rt_list_t        *list,
     return RT_EOK;
 }
 
+
 /**
- * This function will resume the first thread in the list of a IPC object:
- * - remove the thread from suspend queue of IPC object
- * - put the thread into system ready queue
+ * @brief    This function will resume a thread.
+ *
+ * @note     This function will resume the first thread in the list of a IPC object.
+ *           1. remove the thread from suspend queue of a IPC object.
+ *           2. put the thread into system ready queue.
+ *
+ *           By contrast, the rt_ipc_list_resume_all() function will resume all suspended threads
+ *           in the list of a IPC object.
+ *
+ * @param    list is a pointer to a suspended thread list of the IPC object.
  *
- * @param list the thread list
+ * @return   Return the operation status. When the return value is RT_EOK, the function is successfully executed.
+ *           When the return value is any other values, it means this operation failed.
  *
- * @return the operation status, RT_EOK on successful
+ * @warning  This function is generally called by the following functions:
+ *           rt_sem_release(),    rt_mutex_release(),    rt_mb_send_wait(),    rt_mq_send_wait(),
+ *           rt_mb_urgent(),      rt_mb_recv(),          rt_mq_urgent(),       rt_mq_recv(),
  */
 rt_inline rt_err_t rt_ipc_list_resume(rt_list_t *list)
 {
@@ -155,13 +190,19 @@ rt_inline rt_err_t rt_ipc_list_resume(rt_list_t *list)
     return RT_EOK;
 }
 
+
 /**
- * This function will resume all suspended threads in a list, including
- * suspend list of IPC object and private list of mailbox etc.
+ * @brief   This function will resume all suspended threads in the IPC object list,
+ *          including the suspended list of IPC object, and private list of mailbox etc.
+ *
+ * @note    This function will resume all threads in the IPC object list.
+ *          By contrast, the rt_ipc_list_resume() function will resume a suspended thread in the list of a IPC object.
  *
- * @param list of the threads to resume
+ * @param   list is a pointer to a suspended thread list of the IPC object.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the function is successfully executed.
+ *           When the return value is any other values, it means this operation failed.
  *
- * @return the operation status, RT_EOK on successful
  */
 rt_inline rt_err_t rt_ipc_list_resume_all(rt_list_t *list)
 {
@@ -193,17 +234,51 @@ rt_inline rt_err_t rt_ipc_list_resume_all(rt_list_t *list)
     return RT_EOK;
 }
 
+/**@}*/
+
 #ifdef RT_USING_SEMAPHORE
 /**
- * This function will initialize a semaphore and put it under control of
- * resource management.
+ * @addtogroup semaphore
+ */
+
+/**@{*/
+/**
+ * @brief    This function will initialize a static semaphore object.
+ *
+ * @note     For the static semaphore object, its memory space is allocated by the compiler during compiling,
+ *           and shall placed on the read-write data segment or on the uninitialized data segment.
+ *           By contrast, the rt_sem_create() function will allocate memory space automatically and initialize
+ *           the semaphore.
+ *
+ * @see      rt_sem_create()
+ *
+ * @param    sem is a pointer to the semaphore to initialize. It is assumed that storage for the semaphore will be
+ *           allocated in your application.
  *
- * @param sem the semaphore object
- * @param name the name of semaphore
- * @param value the initial value of semaphore
- * @param flag the flag of semaphore
+ * @param    name is a pointer to the name you would like to give the semaphore.
  *
- * @return the operation status, RT_EOK on successful
+ * @param    value is the initial value for the semaphore.
+ *           If used to share resources, you should initialize the value as the number of available resources.
+ *           If used to signal the occurrence of an event, you should initialize the value as 0.
+ *
+ * @param    flag is the semaphore flag, which determines the queuing way of how multiple threads wait
+ *           when the semaphore is not available.
+ *           The semaphore flag can be ONE of the following values:
+ *
+ *               RT_IPC_FLAG_PRIO          The pending threads will queue in order of priority.
+ *
+ *               RT_IPC_FLAG_FIFO          The pending threads will queue in the first-in-first-out method
+ *                                         (also known as first-come-first-served (FCFS) scheduling strategy).
+ *
+ *               NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to
+ *               use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about
+ *               the first-in-first-out principle, and you clearly understand that all threads involved in
+ *               this semaphore will become non-real-time threads.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the initialization is successful.
+ *           If the return value is any other values, it represents the initialization failed.
+ *
+ * @warning  This function can ONLY be called from threads.
  */
 rt_err_t rt_sem_init(rt_sem_t    sem,
                      const char *name,
@@ -229,14 +304,24 @@ rt_err_t rt_sem_init(rt_sem_t    sem,
 }
 RTM_EXPORT(rt_sem_init);
 
+
 /**
- * This function will detach a semaphore from resource management
+ * @brief    This function will detach a static semaphore object.
+ *
+ * @note     This function is used to detach a static semaphore object which is initialized by rt_sem_init() function.
+ *           By contrast, the rt_sem_delete() function will delete a semaphore object.
+ *           When the semaphore is successfully detached, it will resume all suspended threads in the semaphore list.
  *
- * @param sem the semaphore object
+ * @see      rt_sem_delete()
  *
- * @return the operation status, RT_EOK on successful
+ * @param    sem is a pointer to a semaphore object to be detached.
  *
- * @see rt_sem_delete
+ * @return   Return the operation status. When the return value is RT_EOK, the initialization is successful.
+ *           If the return value is any other values, it means that the semaphore detach failed.
+ *
+ * @warning  This function can ONLY detach a static semaphore initialized by the rt_sem_init() function.
+ *           If the semaphore is created by the rt_sem_create() function, you MUST NOT USE this function to detach it,
+ *           ONLY USE the rt_sem_delete() function to complete the deletion.
  */
 rt_err_t rt_sem_detach(rt_sem_t sem)
 {
@@ -257,15 +342,36 @@ RTM_EXPORT(rt_sem_detach);
 
 #ifdef RT_USING_HEAP
 /**
- * This function will create a semaphore from system resource
+ * @brief    Creating a semaphore object.
+ *
+ * @note     For the semaphore object, its memory space is allocated automatically.
+ *           By contrast, the rt_sem_init() function will initialize a static semaphore object.
+ *
+ * @see      rt_sem_init()
+ *
+ * @param    name is a pointer to the name you would like to give the semaphore.
+ *
+ * @param    value is the initial value for the semaphore.
+ *           If used to share resources, you should initialize the value as the number of available resources.
+ *           If used to signal the occurrence of an event, you should initialize the value as 0.
  *
- * @param name the name of semaphore
- * @param value the initial value of semaphore
- * @param flag the flag of semaphore
+ * @param    flag is the semaphore flag, which determines the queuing way of how multiple threads wait
+ *           when the semaphore is not available.
+ *           The semaphore flag can be ONE of the following values:
  *
- * @return the created semaphore, RT_NULL on error happen
+ *               RT_IPC_FLAG_PRIO          The pending threads will queue in order of priority.
  *
- * @see rt_sem_init
+ *               RT_IPC_FLAG_FIFO          The pending threads will queue in the first-in-first-out method
+ *                                         (also known as first-come-first-served (FCFS) scheduling strategy).
+ *
+ *               NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to
+ *               use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about
+ *               the first-in-first-out principle, and you clearly understand that all threads involved in
+ *               this semaphore will become non-real-time threads.
+ *
+ * @return   Return a pointer to the semaphore object. When the return value is RT_NULL, it means the creation failed.
+ *
+ * @warning  This function can NOT be called in interrupt context. You can use macor RT_DEBUG_NOT_IN_INTERRUPT to check it.
  */
 rt_sem_t rt_sem_create(const char *name, rt_uint32_t value, rt_uint8_t flag)
 {
@@ -292,14 +398,24 @@ rt_sem_t rt_sem_create(const char *name, rt_uint32_t value, rt_uint8_t flag)
 }
 RTM_EXPORT(rt_sem_create);
 
+
 /**
- * This function will delete a semaphore object and release the memory
+ * @brief    This function will delete a semaphore object and release the memory space.
  *
- * @param sem the semaphore object
+ * @note     This function is used to delete a semaphore object which is created by the rt_sem_create() function.
+ *           By contrast, the rt_sem_detach() function will detach a static semaphore object.
+ *           When the semaphore is successfully deleted, it will resume all suspended threads in the semaphore list.
  *
- * @return the error code
+ * @see      rt_sem_detach()
  *
- * @see rt_sem_detach
+ * @param    sem is a pointer to a semaphore object to be deleted.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the semaphore detach failed.
+ *
+ * @warning  This function can ONLY delete a semaphore initialized by the rt_sem_create() function.
+ *           If the semaphore is initialized by the rt_sem_init() function, you MUST NOT USE this function to delete it,
+ *           ONLY USE the rt_sem_detach() function to complete the detachment.
  */
 rt_err_t rt_sem_delete(rt_sem_t sem)
 {
@@ -321,14 +437,29 @@ rt_err_t rt_sem_delete(rt_sem_t sem)
 RTM_EXPORT(rt_sem_delete);
 #endif /* RT_USING_HEAP */
 
+
 /**
- * This function will take a semaphore, if the semaphore is unavailable, the
- * thread shall wait for a specified time.
+ * @brief    This function will take a semaphore, if the semaphore is unavailable, the thread shall wait for
+ *           the semaphore up to a specified time.
+ *
+ * @note     When this function is called, the count value of the sem->value will decrease 1 until it is equal to 0.
+ *           When the sem->value is 0, it means that the semaphore is unavailable. At this time, it will suspend the
+ *           thread preparing to take the semaphore.
+ *           On the contrary, the rt_sem_release() function will increase the count value of sem->value by 1 each time.
  *
- * @param sem the semaphore object
- * @param time the waiting time
+ * @see      rt_sem_trytake()
  *
- * @return the error code
+ * @param    sem is a pointer to a semaphore object.
+ *
+ * @param    time is a timeout period (unit: an OS tick). If the semaphore is unavailable, the thread will wait for
+ *           the semaphore up to the amount of time specified by the argument.
+ *           NOTE: Generally, we use the macro RT_WAITING_FOREVER to set this parameter, which means that when the
+ *           semaphore is unavailable, the thread will be waitting forever.
+ *
+ * @return   Return the operation status. ONLY When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the semaphore take failed.
+ *
+ * @warning  This function can ONLY be called in the thread context. It MUST NOT BE called in interrupt context.
  */
 rt_err_t rt_sem_take(rt_sem_t sem, rt_int32_t time)
 {
@@ -418,12 +549,20 @@ rt_err_t rt_sem_take(rt_sem_t sem, rt_int32_t time)
 }
 RTM_EXPORT(rt_sem_take);
 
+
 /**
- * This function will try to take a semaphore and immediately return
+ * @brief    This function will try to take a semaphore, if the semaphore is unavailable, the thread returns immediately.
  *
- * @param sem the semaphore object
+ * @note     This function is very similar to the rt_sem_take() function, when the semaphore is not available,
+ *           the rt_sem_trytake() function will return immediately without waiting for a timeout.
+ *           In other words, rt_sem_trytake(sem) has the same effect as rt_sem_take(sem, 0).
  *
- * @return the error code
+ * @see      rt_sem_take()
+ *
+ * @param    sem is a pointer to a semaphore object.
+ *
+ * @return   Return the operation status. ONLY When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the semaphore take failed.
  */
 rt_err_t rt_sem_trytake(rt_sem_t sem)
 {
@@ -431,13 +570,18 @@ rt_err_t rt_sem_trytake(rt_sem_t sem)
 }
 RTM_EXPORT(rt_sem_trytake);
 
+
 /**
- * This function will release a semaphore, if there are threads suspended on
- * semaphore, it will be waked up.
+ * @brief    This function will release a semaphore. If there is thread suspended on the semaphore, it will get resumed.
+ *
+ * @note     If there are threads suspended on this semaphore, the first thread in the list of this semaphore object
+ *           will be resumed, and a thread scheduling (rt_schedule) will be executed.
+ *           If no threads are suspended on this semaphore, the count value sem->value of this semaphore will increase by 1.
  *
- * @param sem the semaphore object
+ * @param    sem is a pointer to a semaphore object.
  *
- * @return the error code
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the semaphore release failed.
  */
 rt_err_t rt_sem_release(rt_sem_t sem)
 {
@@ -490,14 +634,20 @@ rt_err_t rt_sem_release(rt_sem_t sem)
 }
 RTM_EXPORT(rt_sem_release);
 
+
 /**
- * This function can get or set some extra attributions of a semaphore object.
+ * @brief    This function will set some extra attributions of a semaphore object.
+ *
+ * @note     Currently this function only supports the RT_IPC_CMD_RESET command to reset the semaphore.
+ *
+ * @param    sem is a pointer to a semaphore object.
+ *
+ * @param    cmd is a command word used to configure some attributions of the semaphore.
  *
- * @param sem the semaphore object
- * @param cmd the execution command
- * @param arg the execution argument
+ * @param    arg is the argument of the function to execute the command.
  *
- * @return the error code
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that this function failed to execute.
  */
 rt_err_t rt_sem_control(rt_sem_t sem, int cmd, void *arg)
 {
@@ -533,18 +683,41 @@ rt_err_t rt_sem_control(rt_sem_t sem, int cmd, void *arg)
     return -RT_ERROR;
 }
 RTM_EXPORT(rt_sem_control);
+
+/**@}*/
 #endif /* RT_USING_SEMAPHORE */
 
 #ifdef RT_USING_MUTEX
 /**
- * This function will initialize a mutex and put it under control of resource
- * management.
+ * @addtogroup mutex
+ */
+
+/**@{*/
+
+/**
+ * @brief    Initialize a static mutex object.
+ *
+ * @note     For the static mutex object, its memory space is allocated by the compiler during compiling,
+ *           and shall placed on the read-write data segment or on the uninitialized data segment.
+ *           By contrast, the rt_mutex_create() function will automatically allocate memory space
+ *           and initialize the mutex.
  *
- * @param mutex the mutex object
- * @param name the name of mutex
- * @param flag the flag of mutex
+ * @see      rt_mutex_create()
  *
- * @return the operation status, RT_EOK on successful
+ * @param    mutex is a pointer to the mutex to initialize. It is assumed that storage for the mutex will be
+ *           allocated in your application.
+ *
+ * @param    name is a pointer to the name that given to the mutex.
+ *
+ * @param    flag is the mutex flag, which determines the queuing way of how multiple threads wait
+ *           when the mutex is not available.
+ *           NOTE: The mutex flag can ONLY be RT_IPC_FLAG_PRIO. Using RT_IPC_FLAG_FIFO will seriously affect
+ *           the real-time performance of the system.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the initialization is successful.
+ *           If the return value is any other values, it represents the initialization failed.
+ *
+ * @warning  This function can ONLY be called from threads.
  */
 rt_err_t rt_mutex_init(rt_mutex_t mutex, const char *name, rt_uint8_t flag)
 {
@@ -571,14 +744,24 @@ rt_err_t rt_mutex_init(rt_mutex_t mutex, const char *name, rt_uint8_t flag)
 }
 RTM_EXPORT(rt_mutex_init);
 
+
 /**
- * This function will detach a mutex from resource management
+ * @brief    This function will detach a static mutex object.
  *
- * @param mutex the mutex object
+ * @note     This function is used to detach a static mutex object which is initialized by rt_mutex_init() function.
+ *           By contrast, the rt_mutex_delete() function will delete a mutex object.
+ *           When the mutex is successfully detached, it will resume all suspended threads in the mutex list.
  *
- * @return the operation status, RT_EOK on successful
+ * @see      rt_mutex_delete()
  *
- * @see rt_mutex_delete
+ * @param    mutex is a pointer to a mutex object to be detached.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the initialization is successful.
+ *           If the return value is any other values, it means that the mutex detach failed.
+ *
+ * @warning  This function can ONLY detach a static mutex initialized by the rt_mutex_init() function.
+ *           If the mutex is created by the rt_mutex_create() function, you MUST NOT USE this function to detach it,
+ *           ONLY USE the rt_mutex_delete() function to complete the deletion.
  */
 rt_err_t rt_mutex_detach(rt_mutex_t mutex)
 {
@@ -599,14 +782,23 @@ RTM_EXPORT(rt_mutex_detach);
 
 #ifdef RT_USING_HEAP
 /**
- * This function will create a mutex from system resource
+ * @brief    This function will create a mutex object.
+ *
+ * @note     For the mutex object, its memory space is automatically allocated.
+ *           By contrast, the rt_mutex_init() function will initialize a static mutex object.
+ *
+ * @see      rt_mutex_init()
  *
- * @param name the name of mutex
- * @param flag the flag of mutex
+ * @param    name is a pointer to the name that given to the mutex.
  *
- * @return the created mutex, RT_NULL on error happen
+ * @param    flag is the mutex flag, which determines the queuing way of how multiple threads wait
+ *           when the mutex is not available.
+ *           NOTE: The mutex flag can ONLY be RT_IPC_FLAG_PRIO. Using RT_IPC_FLAG_FIFO will seriously affect
+ *           the real-time performance of the system.
  *
- * @see rt_mutex_init
+ * @return   Return a pointer to the mutex object. When the return value is RT_NULL, it means the creation failed.
+ *
+ * @warning  This function can ONLY be called from threads.
  */
 rt_mutex_t rt_mutex_create(const char *name, rt_uint8_t flag)
 {
@@ -635,14 +827,24 @@ rt_mutex_t rt_mutex_create(const char *name, rt_uint8_t flag)
 }
 RTM_EXPORT(rt_mutex_create);
 
+
 /**
- * This function will delete a mutex object and release the memory
+ * @brief    This function will delete a mutex object and release this memory space.
+ *
+ * @note     This function is used to delete a mutex object which is created by the rt_mutex_create() function.
+ *           By contrast, the rt_mutex_detach() function will detach a static mutex object.
+ *           When the mutex is successfully deleted, it will resume all suspended threads in the mutex list.
+ *
+ * @see      rt_mutex_detach()
  *
- * @param mutex the mutex object
+ * @param    mutex is a pointer to a mutex object to be deleted.
  *
- * @return the error code
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the mutex detach failed.
  *
- * @see rt_mutex_detach
+ * @warning  This function can ONLY delete a mutex initialized by the rt_mutex_create() function.
+ *           If the mutex is initialized by the rt_mutex_init() function, you MUST NOT USE this function to delete it,
+ *           ONLY USE the rt_mutex_detach() function to complete the detachment.
  */
 rt_err_t rt_mutex_delete(rt_mutex_t mutex)
 {
@@ -664,14 +866,29 @@ rt_err_t rt_mutex_delete(rt_mutex_t mutex)
 RTM_EXPORT(rt_mutex_delete);
 #endif /* RT_USING_HEAP */
 
+
 /**
- * This function will take a mutex, if the mutex is unavailable, the
- * thread shall wait for a specified time.
+ * @brief    This function will take a mutex, if the mutex is unavailable, the thread shall wait for
+ *           the mutex up to a specified time.
+ *
+ * @note     When this function is called, the count value of the sem->value will decrease 1 until it is equal to 0.
+ *           When the sem->value is 0, it means that the mutex is unavailable. At this time, it will suspend the
+ *           thread preparing to take the mutex.
+ *           On the contrary, the rt_sem_release() function will increase the count value of sem->value by 1 each time.
+ *
+ * @see      rt_mutex_trytake()
+ *
+ * @param    mutex is a pointer to a mutex object.
  *
- * @param mutex the mutex object
- * @param time the waiting time
+ * @param    time is a timeout period (unit: an OS tick). If the mutex is unavailable, the thread will wait for
+ *           the mutex up to the amount of time specified by the argument.
+ *           NOTE: Generally, we set this parameter to RT_WAITING_FOREVER, which means that when the mutex is unavailable,
+ *           the thread will be waitting forever.
  *
- * @return the error code
+ * @return   Return the operation status. ONLY When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the mutex take failed.
+ *
+ * @warning  This function can ONLY be called in the thread context. It MUST NOT BE called in interrupt context.
  */
 rt_err_t rt_mutex_take(rt_mutex_t mutex, rt_int32_t time)
 {
@@ -821,12 +1038,21 @@ __again:
 }
 RTM_EXPORT(rt_mutex_take);
 
+
 /**
- * This function will try to take a mutex and immediately return
+ * @brief    This function will try to take a mutex, if the mutex is unavailable, the thread returns immediately.
+ *
+ * @note     This function is very similar to the rt_mutex_take() function, when the mutex is not available,
+ *           except that rt_mutex_trytake() will return immediately without waiting for a timeout
+ *           when the mutex is not available.
+ *           In other words, rt_mutex_trytake(mutex) has the same effect as rt_mutex_take(mutex, 0).
+ *
+ * @see      rt_mutex_take()
  *
- * @param mutex the mutex object
+ * @param    mutex is a pointer to a mutex object.
  *
- * @return the error code
+ * @return   Return the operation status. ONLY When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the mutex take failed.
  */
 rt_err_t rt_mutex_trytake(rt_mutex_t mutex)
 {
@@ -834,13 +1060,18 @@ rt_err_t rt_mutex_trytake(rt_mutex_t mutex)
 }
 RTM_EXPORT(rt_mutex_trytake);
 
+
 /**
- * This function will release a mutex, if there are threads suspended on mutex,
- * it will be waked up.
+ * @brief    This function will release a mutex. If there is thread suspended on the mutex, the thread will be resumed.
+ *
+ * @note     If there are threads suspended on this mutex, the first thread in the list of this mutex object
+ *           will be resumed, and a thread scheduling (rt_schedule) will be executed.
+ *           If no threads are suspended on this mutex, the count value mutex->value of this mutex will increase by 1.
  *
- * @param mutex the mutex object
+ * @param    mutex is a pointer to a mutex object.
  *
- * @return the error code
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the mutex release failed.
  */
 rt_err_t rt_mutex_release(rt_mutex_t mutex)
 {
@@ -953,14 +1184,20 @@ rt_err_t rt_mutex_release(rt_mutex_t mutex)
 }
 RTM_EXPORT(rt_mutex_release);
 
+
 /**
- * This function can get or set some extra attributions of a mutex object.
+ * @brief    This function will set some extra attributions of a mutex object.
+ *
+ * @note     Currently this function does not implement the control function.
  *
- * @param mutex the mutex object
- * @param cmd the execution command
- * @param arg the execution argument
+ * @param    mutex is a pointer to a mutex object.
  *
- * @return the error code
+ * @param    cmd is a command word used to configure some attributions of the mutex.
+ *
+ * @param    arg is the argument of the function to execute the command.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that this function failed to execute.
  */
 rt_err_t rt_mutex_control(rt_mutex_t mutex, int cmd, void *arg)
 {
@@ -971,18 +1208,54 @@ rt_err_t rt_mutex_control(rt_mutex_t mutex, int cmd, void *arg)
     return -RT_ERROR;
 }
 RTM_EXPORT(rt_mutex_control);
+
+/**@}*/
 #endif /* RT_USING_MUTEX */
 
 #ifdef RT_USING_EVENT
 /**
- * This function will initialize an event and put it under control of resource
- * management.
+ * @addtogroup event
+ */
+
+/**@{*/
+
+/**
+ * @brief    The function will initialize a static event object.
+ *
+ * @note     For the static event object, its memory space is allocated by the compiler during compiling,
+ *           and shall placed on the read-write data segment or on the uninitialized data segment.
+ *           By contrast, the rt_event_create() function will allocate memory space automatically
+ *           and initialize the event.
+ *
+ * @see      rt_event_create()
+ *
+ * @param    event is a pointer to the event to initialize. It is assumed that storage for the event
+ *           will be allocated in your application.
+ *
+ * @param    name is a pointer to the name that given to the event.
+ *
+ * @param    value is the initial value for the event.
+ *           If want to share resources, you should initialize the value as the number of available resources.
+ *           If want to signal the occurrence of an event, you should initialize the value as 0.
+ *
+ * @param    flag is the event flag, which determines the queuing way of how multiple threads wait
+ *           when the event is not available.
+ *           The event flag can be ONE of the following values:
+ *
+ *               RT_IPC_FLAG_PRIO          The pending threads will queue in order of priority.
  *
- * @param event the event object
- * @param name the name of event
- * @param flag the flag of event
+ *               RT_IPC_FLAG_FIFO          The pending threads will queue in the first-in-first-out method
+ *                                         (also known as first-come-first-served (FCFS) scheduling strategy).
  *
- * @return the operation status, RT_EOK on successful
+ *               NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to
+ *               use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about
+ *               the first-in-first-out principle, and you clearly understand that all threads involved in
+ *               this event will become non-real-time threads.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the initialization is successful.
+ *           If the return value is any other values, it represents the initialization failed.
+ *
+ * @warning  This function can ONLY be called from threads.
  */
 rt_err_t rt_event_init(rt_event_t event, const char *name, rt_uint8_t flag)
 {
@@ -1005,12 +1278,24 @@ rt_err_t rt_event_init(rt_event_t event, const char *name, rt_uint8_t flag)
 }
 RTM_EXPORT(rt_event_init);
 
+
 /**
- * This function will detach an event object from resource management
+ * @brief    This function will detach a static event object.
+ *
+ * @note     This function is used to detach a static event object which is initialized by rt_event_init() function.
+ *           By contrast, the rt_event_delete() function will delete an event object.
+ *           When the event is successfully detached, it will resume all suspended threads in the event list.
  *
- * @param event the event object
+ * @see      rt_event_delete()
  *
- * @return the operation status, RT_EOK on successful
+ * @param    event is a pointer to an event object to be detached.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the initialization is successful.
+ *           If the return value is any other values, it means that the event detach failed.
+ *
+ * @warning  This function can ONLY detach a static event initialized by the rt_event_init() function.
+ *           If the event is created by the rt_event_create() function, you MUST NOT USE this function to detach it,
+ *           ONLY USE the rt_event_delete() function to complete the deletion.
  */
 rt_err_t rt_event_detach(rt_event_t event)
 {
@@ -1031,12 +1316,32 @@ RTM_EXPORT(rt_event_detach);
 
 #ifdef RT_USING_HEAP
 /**
- * This function will create an event object from system resource
+ * @brief    Creating an event object.
+ *
+ * @note     For the event object, its memory space is allocated automatically.
+ *           By contrast, the rt_event_init() function will initialize a static event object.
+ *
+ * @see      rt_event_init()
  *
- * @param name the name of event
- * @param flag the flag of event
+ * @param    name is a pointer to the name that given to the event.
  *
- * @return the created event, RT_NULL on error happen
+ * @param    flag is the event flag, which determines the queuing way of how multiple threads wait when the event
+ *           is not available.
+ *           The event flag can be ONE of the following values:
+ *
+ *               RT_IPC_FLAG_PRIO          The pending threads will queue in order of priority.
+ *
+ *               RT_IPC_FLAG_FIFO          The pending threads will queue in the first-in-first-out method
+ *                                         (also known as first-come-first-served (FCFS) scheduling strategy).
+ *
+ *               NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to
+ *               use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about
+ *               the first-in-first-out principle, and you clearly understand that all threads involved in
+ *               this event will become non-real-time threads.
+ *
+ * @return   Return a pointer to the event object. When the return value is RT_NULL, it means the creation failed.
+ *
+ * @warning  This function can ONLY be called from threads.
  */
 rt_event_t rt_event_create(const char *name, rt_uint8_t flag)
 {
@@ -1062,12 +1367,24 @@ rt_event_t rt_event_create(const char *name, rt_uint8_t flag)
 }
 RTM_EXPORT(rt_event_create);
 
+
 /**
- * This function will delete an event object and release the memory
+ * @brief    This function will delete an event object and release the memory space.
+ *
+ * @note     This function is used to delete an event object which is created by the rt_event_create() function.
+ *           By contrast, the rt_event_detach() function will detach a static event object.
+ *           When the event is successfully deleted, it will resume all suspended threads in the event list.
+ *
+ * @see      rt_event_detach()
  *
- * @param event the event object
+ * @param    event is a pointer to an event object to be deleted.
  *
- * @return the error code
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the event detach failed.
+ *
+ * @warning  This function can ONLY delete an event initialized by the rt_event_create() function.
+ *           If the event is initialized by the rt_event_init() function, you MUST NOT USE this function to delete it,
+ *           ONLY USE the rt_event_detach() function to complete the detachment.
  */
 rt_err_t rt_event_delete(rt_event_t event)
 {
@@ -1089,14 +1406,23 @@ rt_err_t rt_event_delete(rt_event_t event)
 RTM_EXPORT(rt_event_delete);
 #endif /* RT_USING_HEAP */
 
+
 /**
- * This function will send an event to the event object, if there are threads
- * suspended on event object, it will be waked up.
+ * @brief    This function will send an event to the event object.
+ *           If there is a thread suspended on the event, the thread will be resumed.
+ *
+ * @note     When using this function, you need to use the parameter (set) to specify the event flag of the event object,
+ *           then the function will traverse the list of suspended threads waiting on the event object.
+ *           If there is a thread suspended on the event, and the thread's event_info and the event flag of
+ *           the current event object matches, the thread will be resumed.
+ *
+ * @param    event is a pointer to the event object to be sent.
  *
- * @param event the event object
- * @param set the event set
+ * @param    set is a flag that you will set for this event's flag.
+ *           You can set an event flag, or you can set multiple flags through OR logic operation.
  *
- * @return the error code
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the event detach failed.
  */
 rt_err_t rt_event_send(rt_event_t event, rt_uint32_t set)
 {
@@ -1190,18 +1516,38 @@ rt_err_t rt_event_send(rt_event_t event, rt_uint32_t set)
 }
 RTM_EXPORT(rt_event_send);
 
+
 /**
- * This function will receive an event from event object, if the event is
- * unavailable, the thread shall wait for a specified time.
+ * @brief  This function will receive an event from event object. if the event is unavailable, the thread shall wait for
+ *         the event up to a specified time.
+ *
+ * @note   If there are threads suspended on this semaphore, the first thread in the list of this semaphore object
+ *         will be resumed, and a thread scheduling (rt_schedule) will be executed.
+ *         If no threads are suspended on this semaphore, the count value sem->value of this semaphore will increase by 1.
+ *
+ * @param    event is a pointer to the event object to be received.
+ *
+ * @param    set is a flag that you will set for this event's flag.
+ *           You can set an event flag, or you can set multiple flags through OR logic operation.
  *
- * @param event the fast event object
- * @param set the interested event set
- * @param option the receive option, either RT_EVENT_FLAG_AND or
- *        RT_EVENT_FLAG_OR should be set.
- * @param timeout the waiting time
- * @param recved the received event, if you don't care, RT_NULL can be set.
+ * @param    option is the option of this receiving event, it indicates how the receiving event is operated.
+ *           The option can be one or more of the following values, When selecting multiple values,use logical OR to operate.
+ *           (NOTE: RT_EVENT_FLAG_OR and RT_EVENT_FLAG_AND can only select one):
  *
- * @return the error code
+ *
+ *               RT_EVENT_FLAG_OR           The thread select to use logical OR to receive the event.
+ *
+ *               RT_EVENT_FLAG_AND          The thread select to use logical OR to receive the event.
+ *
+ *               RT_EVENT_FLAG_CLEAR        When the thread receives the corresponding event, the function
+ *                                          determines whether to clear the event flag.
+ *
+ * @param    timeout is a timeout period (unit: an OS tick).
+ *
+ * @param    recved is a pointer to the received event. If you don't care about this value, you can use RT_NULL to set.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the semaphore release failed.
  */
 rt_err_t rt_event_recv(rt_event_t   event,
                        rt_uint32_t  set,
@@ -1325,14 +1671,20 @@ rt_err_t rt_event_recv(rt_event_t   event,
 }
 RTM_EXPORT(rt_event_recv);
 
+
 /**
- * This function can get or set some extra attributions of an event object.
+ * @brief    This function will set some extra attributions of an event object.
+ *
+ * @note     Currently this function only supports the RT_IPC_CMD_RESET command to reset the event.
+ *
+ * @param    event is a pointer to an event object.
  *
- * @param event the event object
- * @param cmd the execution command
- * @param arg the execution argument
+ * @param    cmd is a command word used to configure some attributions of the event.
  *
- * @return the error code
+ * @param    arg is the argument of the function to execute the command.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that this function failed to execute.
  */
 rt_err_t rt_event_control(rt_event_t event, int cmd, void *arg)
 {
@@ -1364,20 +1716,55 @@ rt_err_t rt_event_control(rt_event_t event, int cmd, void *arg)
     return -RT_ERROR;
 }
 RTM_EXPORT(rt_event_control);
+
+/**@}*/
 #endif /* RT_USING_EVENT */
 
 #ifdef RT_USING_MAILBOX
 /**
- * This function will initialize a mailbox and put it under control of resource
- * management.
+ * @addtogroup mailbox
+ */
+
+/**@{*/
+
+/**
+ * @brief    Initialize a static mailbox object.
  *
- * @param mb the mailbox object
- * @param name the name of mailbox
- * @param msgpool the begin address of buffer to save received mail
- * @param size the size of mailbox
- * @param flag the flag of mailbox
+ * @note     For the static mailbox object, its memory space is allocated by the compiler during compiling,
+ *           and shall placed on the read-write data segment or on the uninitialized data segment.
+ *           By contrast, the rt_mb_create() function will allocate memory space automatically and initialize the mailbox.
  *
- * @return the operation status, RT_EOK on successful
+ * @see      rt_mb_create()
+ *
+ * @param    mb is a pointer to the mailbox to initialize.
+ *           It is assumed that storage for the mailbox will be allocated in your application.
+ *
+ * @param    name is a pointer to the name that given to the mailbox.
+ *
+ * @param    msgpoll is a pointer to the starting address of the memory space you allocated for the mailbox in advance.
+ *           In other words, msgpoll is a pointer to the mailbox buffer of the starting address.
+ *
+ * @param    size is the maximum number of mails in the mailbox.
+ *           For example, when the mailbox buffer capacity is N, size is N/4.
+ *
+ * @param    flag is the mailbox flag, which determines the queuing way of how multiple threads wait
+ *           when the mailbox is not available.
+ *           The mailbox flag can be ONE of the following values:
+ *
+ *               RT_IPC_FLAG_PRIO          The pending threads will queue in order of priority.
+ *
+ *               RT_IPC_FLAG_FIFO          The pending threads will queue in the first-in-first-out method
+ *                                       (also known as first-come-first-served (FCFS) scheduling strategy).
+ *
+ *               NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to
+ *               use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about
+ *               the first-in-first-out principle, and you clearly understand that all threads involved in
+ *               this mailbox will become non-real-time threads.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the initialization is successful.
+ *           If the return value is any other values, it represents the initialization failed.
+ *
+ * @warning  This function can ONLY be called from threads.
  */
 rt_err_t rt_mb_init(rt_mailbox_t mb,
                     const char  *name,
@@ -1410,12 +1797,24 @@ rt_err_t rt_mb_init(rt_mailbox_t mb,
 }
 RTM_EXPORT(rt_mb_init);
 
+
 /**
- * This function will detach a mailbox from resource management
+ * @brief    This function will detach a static mailbox object.
+ *
+ * @note     This function is used to detach a static mailbox object which is initialized by rt_mb_init() function.
+ *           By contrast, the rt_mb_delete() function will delete a mailbox object.
+ *           When the mailbox is successfully detached, it will resume all suspended threads in the mailbox list.
  *
- * @param mb the mailbox object
+ * @see      rt_mb_delete()
  *
- * @return the operation status, RT_EOK on successful
+ * @param    mb is a pointer to a mailbox object to be detached.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the initialization is successful.
+ *           If the return value is any other values, it means that the mailbox detach failed.
+ *
+ * @warning  This function can ONLY detach a static mailbox initialized by the rt_mb_init() function.
+ *           If the mailbox is created by the rt_mb_create() function, you MUST NOT USE this function to detach it,
+ *           ONLY USE the rt_mb_delete() function to complete the deletion.
  */
 rt_err_t rt_mb_detach(rt_mailbox_t mb)
 {
@@ -1438,13 +1837,35 @@ RTM_EXPORT(rt_mb_detach);
 
 #ifdef RT_USING_HEAP
 /**
- * This function will create a mailbox object from system resource
+ * @brief  Creating a mailbox object.
+ *
+ * @note   For the mailbox object, its memory space is allocated automatically.
+ *         By contrast, the rt_mb_init() function will initialize a static mailbox object.
+ *
+ * @see    rt_mb_init()
  *
- * @param name the name of mailbox
- * @param size the size of mailbox
- * @param flag the flag of mailbox
+ * @param  name is a pointer that given to the mailbox.
  *
- * @return the created mailbox, RT_NULL on error happen
+ * @param    size is the maximum number of mails in the mailbox.
+ *           For example, when mailbox buffer capacity is N, size is N/4.
+ *
+ * @param    flag is the mailbox flag, which determines the queuing way of how multiple threads wait
+ *           when the mailbox is not available.
+ *           The mailbox flag can be ONE of the following values:
+ *
+ *               RT_IPC_FLAG_PRIO          The pending threads will queue in order of priority.
+ *
+ *               RT_IPC_FLAG_FIFO          The pending threads will queue in the first-in-first-out method
+ *                                         (also known as first-come-first-served (FCFS) scheduling strategy).
+ *
+ *               NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to
+ *               use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about
+ *               the first-in-first-out principle, and you clearly understand that all threads involved in
+ *               this mailbox will become non-real-time threads.
+ *
+ * @return   Return a pointer to the mailbox object. When the return value is RT_NULL, it means the creation failed.
+ *
+ * @warning  This function can ONLY be called from threads.
  */
 rt_mailbox_t rt_mb_create(const char *name, rt_size_t size, rt_uint8_t flag)
 {
@@ -1484,12 +1905,24 @@ rt_mailbox_t rt_mb_create(const char *name, rt_size_t size, rt_uint8_t flag)
 }
 RTM_EXPORT(rt_mb_create);
 
+
 /**
- * This function will delete a mailbox object and release the memory
+ * @brief    This function will delete a mailbox object and release the memory space.
+ *
+ * @note     This function is used to delete a mailbox object which is created by the rt_mb_create() function.
+ *           By contrast, the rt_mb_detach() function will detach a static mailbox object.
+ *           When the mailbox is successfully deleted, it will resume all suspended threads in the mailbox list.
  *
- * @param mb the mailbox object
+ * @see      rt_mb_detach()
  *
- * @return the error code
+ * @param    mb is a pointer to a mailbox object to be deleted.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the mailbox detach failed.
+ *
+ * @warning  This function can only delete mailbox created by the rt_mb_create() function.
+ *           If the mailbox is initialized by the rt_mb_init() function, you MUST NOT USE this function to delete it,
+ *           ONLY USE the rt_mb_detach() function to complete the detachment.
  */
 rt_err_t rt_mb_delete(rt_mailbox_t mb)
 {
@@ -1517,15 +1950,29 @@ rt_err_t rt_mb_delete(rt_mailbox_t mb)
 RTM_EXPORT(rt_mb_delete);
 #endif /* RT_USING_HEAP */
 
+
 /**
- * This function will send a mail to mailbox object. If the mailbox is full,
- * current thread will be suspended until timeout.
+ * @brief    This function will send an mail to the mailbox object. If there is a thread suspended on the mailbox,
+ *           the thread will be resumed.
+ *
+ * @note     When using this function to send a mail, if the mailbox if fully used, the current thread will
+ *           wait for a timeout. If the set timeout time is reached and there is still no space available,
+ *           the sending thread will be resumed and an error code will be returned.
+ *           By contrast, the rt_mb_send() function will return an error code immediately without waiting time
+ *           when the mailbox if fully used.
+ *
+ * @see      rt_mb_send()
+ *
+ * @param    mb is a pointer to the mailbox object to be sent.
+ *
+ * @param    value is a value to the content of the mail you want to send.
+ *
+ * @param    timeout is a timeout period (unit: an OS tick).
  *
- * @param mb the mailbox object
- * @param value the mail
- * @param timeout the waiting time
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the mailbox detach failed.
  *
- * @return the error code
+ * @warning  This function can be called in interrupt context and thread context.
  */
 rt_err_t rt_mb_send_wait(rt_mailbox_t mb,
                          rt_ubase_t   value,
@@ -1657,15 +2104,23 @@ rt_err_t rt_mb_send_wait(rt_mailbox_t mb,
 }
 RTM_EXPORT(rt_mb_send_wait);
 
+
 /**
- * This function will send a mail to mailbox object, if there are threads
- * suspended on mailbox object, it will be waked up. This function will return
- * immediately, if you want blocking send, use rt_mb_send_wait instead.
+ * @brief    This function will send an mail to the mailbox object. If there is a thread suspended on the mailbox,
+ *           the thread will be resumed.
+ *
+ * @note     When using this function to send a mail, if the mailbox is fully used, this function will return an error
+ *           code immediately without waiting time.
+ *           By contrast, the rt_mb_send_wait() function is set a timeout to wait for the mail to be sent.
+ *
+ * @see      rt_mb_send_wait()
+ *
+ * @param    mb is a pointer to the mailbox object to be sent.
  *
- * @param mb the mailbox object
- * @param value the mail
+ * @param    value is a value to the content of the mail you want to send.
  *
- * @return the error code
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the mailbox detach failed.
  */
 rt_err_t rt_mb_send(rt_mailbox_t mb, rt_ubase_t value)
 {
@@ -1673,15 +2128,22 @@ rt_err_t rt_mb_send(rt_mailbox_t mb, rt_ubase_t value)
 }
 RTM_EXPORT(rt_mb_send);
 
+
 /**
- * This function will send an urgent mail to mailbox object, if there are threads
- * suspended on mailbox object, it will be waked up. This function will return
- * immediately.
+ * @brief    This function will send an urgent mail to the mailbox object.
+ *
+ * @note     This function is almost the same as the rt_mb_send() function. The only difference is that
+ *           when sending an urgent mail, the mail will be placed at the head of the mail queue so that
+ *           the recipient can receive the urgent mail first.
+ *
+ * @see      rt_mb_send()
+ *
+ * @param    mb is a pointer to the mailbox object to be sent.
  *
- * @param mb the mailbox object
- * @param value the mail
+ * @param    value is the content of the mail you want to send.
  *
- * @return the error code
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the mailbox detach failed.
  */
 rt_err_t rt_mb_urgent(rt_mailbox_t mb, rt_ubase_t value)
 {
@@ -1738,15 +2200,24 @@ rt_err_t rt_mb_urgent(rt_mailbox_t mb, rt_ubase_t value)
 }
 RTM_EXPORT(rt_mb_urgent);
 
+
 /**
- * This function will receive a mail from mailbox object, if there is no mail
- * in mailbox object, the thread shall wait for a specified time.
+ * @brief    This function will receive a mail from mailbox object, if there is no mail in mailbox object,
+ *           the thread shall wait for a specified time.
+ *
+ * @note     Only when there is mail in the mailbox, the receiving thread can get the mail immediately and
+ *           return RT_EOK, otherwise the receiving thread will be suspended until the set timeout. If the mail
+ *           is still not received within the specified time, it will return-RT_ETIMEOUT.
+ *
+ * @param    mb is a pointer to the mailbox object to be received.
+ *
+ * @param    value is a flag that you will set for this mailbox's flag.
+ *           You can set an mailbox flag, or you can set multiple flags through OR logic operations.
  *
- * @param mb the mailbox object
- * @param value the received mail will be saved in
- * @param timeout the waiting time
+ * @param    timeout is a timeout period (unit: an OS tick).
  *
- * @return the error code
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the mailbox release failed.
  */
 rt_err_t rt_mb_recv(rt_mailbox_t mb, rt_ubase_t *value, rt_int32_t timeout)
 {
@@ -1879,14 +2350,20 @@ rt_err_t rt_mb_recv(rt_mailbox_t mb, rt_ubase_t *value, rt_int32_t timeout)
 }
 RTM_EXPORT(rt_mb_recv);
 
+
 /**
- * This function can get or set some extra attributions of a mailbox object.
+ * @brief    This function will set some extra attributions of a mailbox object.
+ *
+ * @note     Currently this function only supports the RT_IPC_CMD_RESET command to reset the mailbox.
+ *
+ * @param    mb is a pointer to a mailbox object.
+ *
+ * @param    cmd is a command used to configure some attributions of the mailbox.
  *
- * @param mb the mailbox object
- * @param cmd the execution command
- * @param arg the execution argument
+ * @param    arg is the argument of the function to execute the command.
  *
- * @return the error code
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that this function failed to execute.
  */
 rt_err_t rt_mb_control(rt_mailbox_t mb, int cmd, void *arg)
 {
@@ -1922,26 +2399,64 @@ rt_err_t rt_mb_control(rt_mailbox_t mb, int cmd, void *arg)
     return -RT_ERROR;
 }
 RTM_EXPORT(rt_mb_control);
+
+/**@}*/
 #endif /* RT_USING_MAILBOX */
 
 #ifdef RT_USING_MESSAGEQUEUE
+/**
+ * @addtogroup messagequeue
+ */
+
+/**@{*/
+
 struct rt_mq_message
 {
     struct rt_mq_message *next;
 };
 
+
 /**
- * This function will initialize a message queue and put it under control of
- * resource management.
+ * @brief    Initialize a static messagequeue object.
+ *
+ * @note     For the static messagequeue object, its memory space is allocated by the compiler during compiling,
+ *           and shall placed on the read-write data segment or on the uninitialized data segment.
+ *           By contrast, the rt_mq_create() function will allocate memory space automatically
+ *           and initialize the messagequeue.
+ *
+ * @see      rt_mq_create()
+ *
+ * @param    mq is a pointer to the messagequeue to initialize. It is assumed that storage for
+ *           the messagequeue will be allocated in your application.
+ *
+ * @param    name is a pointer to the name that given to the messagequeue.
+ *
+ * @param    msgpool is a pointer to the starting address of the memory space you allocated for
+ *           the messagequeue in advance.
+ *           In other words, msgpool is a pointer to the messagequeue buffer of the starting address.
+ *
+ * @param    msg_size is the maximum length of a message in the messagequeue (Unit: Byte).
+ *
+ * @param    pool_size is the size of the memory space allocated for the messagequeue in advance.
+ *
+ * @param    flag is the messagequeue flag, which determines the queuing way of how multiple threads wait
+ *           when the messagequeue is not available.
+ *           The messagequeue flag can be ONE of the following values:
+ *
+ *               RT_IPC_FLAG_PRIO          The pending threads will queue in order of priority.
  *
- * @param mq the message object
- * @param name the name of message queue
- * @param msgpool the beginning address of buffer to save messages
- * @param msg_size the maximum size of message
- * @param pool_size the size of buffer to save messages
- * @param flag the flag of message queue
+ *               RT_IPC_FLAG_FIFO          The pending threads will queue in the first-in-first-out method
+ *                                         (also known as first-come-first-served (FCFS) scheduling strategy).
  *
- * @return the operation status, RT_EOK on successful
+ *               NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to
+ *               use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about
+ *               the first-in-first-out principle, and you clearly understand that all threads involved in
+ *               this messagequeue will become non-real-time threads.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the initialization is successful.
+ *           If the return value is any other values, it represents the initialization failed.
+ *
+ * @warning  This function can ONLY be called from threads.
  */
 rt_err_t rt_mq_init(rt_mq_t     mq,
                     const char *name,
@@ -1996,12 +2511,24 @@ rt_err_t rt_mq_init(rt_mq_t     mq,
 }
 RTM_EXPORT(rt_mq_init);
 
+
 /**
- * This function will detach a message queue object from resource management
+ * @brief    This function will detach a static messagequeue object.
+ *
+ * @note     This function is used to detach a static messagequeue object which is initialized by rt_mq_init() function.
+ *           By contrast, the rt_mq_delete() function will delete a messagequeue object.
+ *           When the messagequeue is successfully detached, it will resume all suspended threads in the messagequeue list.
  *
- * @param mq the message queue object
+ * @see      rt_mq_delete()
  *
- * @return the operation status, RT_EOK on successful
+ * @param    mq is a pointer to a messagequeue object to be detached.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the initialization is successful.
+ *           If the return value is any other values, it means that the messagequeue detach failed.
+ *
+ * @warning  This function can ONLY detach a static messagequeue initialized by the rt_mq_init() function.
+ *           If the messagequeue is created by the rt_mq_create() function, you MUST NOT USE this function to detach it,
+ *           and ONLY USE the rt_mq_delete() function to complete the deletion.
  */
 rt_err_t rt_mq_detach(rt_mq_t mq)
 {
@@ -2024,14 +2551,36 @@ RTM_EXPORT(rt_mq_detach);
 
 #ifdef RT_USING_HEAP
 /**
- * This function will create a message queue object from system resource
+ * @brief    Creating a messagequeue object.
+ *
+ * @note     For the messagequeue object, its memory space is allocated automatically.
+ *           By contrast, the rt_mq_init() function will initialize a static messagequeue object.
+ *
+ * @see      rt_mq_init()
  *
- * @param name the name of message queue
- * @param msg_size the size of message
- * @param max_msgs the maximum number of message in queue
- * @param flag the flag of message queue
+ * @param    name is a pointer that given to the messagequeue.
  *
- * @return the created message queue, RT_NULL on error happen
+ * @param    msg_size is the maximum length of a message in the messagequeue (Unit: Byte).
+ *
+ * @param    max_msgs is the maximum number of messages in the messagequeue.
+ *
+ * @param    flag is the messagequeue flag, which determines the queuing way of how multiple threads wait
+ *           when the messagequeue is not available.
+ *           The messagequeue flag can be ONE of the following values:
+ *
+ *               RT_IPC_FLAG_PRIO          The pending threads will queue in order of priority.
+ *
+ *               RT_IPC_FLAG_FIFO          The pending threads will queue in the first-in-first-out method
+ *                                         (also known as first-come-first-served (FCFS) scheduling strategy).
+ *
+ *               NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to
+ *               use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about
+ *               the first-in-first-out principle, and you clearly understand that all threads involved in
+ *               this messagequeue will become non-real-time threads.
+ *
+ * @return   Return a pointer to the messagequeue object. When the return value is RT_NULL, it means the creation failed.
+ *
+ * @warning  This function can NOT be called in interrupt context. You can use macor RT_DEBUG_NOT_IN_INTERRUPT to check it.
  */
 rt_mq_t rt_mq_create(const char *name,
                      rt_size_t   msg_size,
@@ -2094,12 +2643,25 @@ rt_mq_t rt_mq_create(const char *name,
 }
 RTM_EXPORT(rt_mq_create);
 
+
 /**
- * This function will delete a message queue object and release the memory
+ * @brief    This function will delete a messagequeue object and release the memory.
  *
- * @param mq the message queue object
+ * @note     This function is used to delete a messagequeue object which is created by the rt_mq_create() function.
+ *           By contrast, the rt_mq_detach() function will detach a static messagequeue object.
+ *           When the messagequeue is successfully deleted, it will resume all suspended threads in the messagequeue list.
  *
- * @return the error code
+ * @see      rt_mq_detach()
+ *
+ * @param    mq is a pointer to a messagequeue object to be deleted.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the messagequeue detach failed.
+ *
+ * @warning  This function can ONLY delete a messagequeue initialized by the rt_mq_create() function.
+ *           If the messagequeue is initialized by the rt_mq_init() function, you MUST NOT USE this function to delete it,
+ *           ONLY USE the rt_mq_detach() function to complete the detachment.
+ *           for example,the rt_mq_create() function, it cannot be called in interrupt context.
  */
 rt_err_t rt_mq_delete(rt_mq_t mq)
 {
@@ -2126,16 +2688,35 @@ rt_err_t rt_mq_delete(rt_mq_t mq)
 RTM_EXPORT(rt_mq_delete);
 #endif /* RT_USING_HEAP */
 
+
 /**
- * This function will send a message to message queue object. If the message queue is full,
- * current thread will be suspended until timeout.
+ * @brief    This function will send a message to the messagequeue object. If
+ *           there is a thread suspended on the messagequeue, the thread will be
+ *           resumed.
+ *
+ * @note     When using this function to send a message, if the messagequeue is
+ *           fully used, the current thread will wait for a timeout. If reaching
+ *           the timeout and there is still no space available, the sending
+ *           thread will be resumed and an error code will be returned. By
+ *           contrast, the rt_mq_send() function will return an error code
+ *           immediately without waiting when the messagequeue if fully used.
+ *
+ * @see      rt_mq_send()
+ *
+ * @param    mq is a pointer to the messagequeue object to be sent.
+ *
+ * @param    buffer is the content of the message.
  *
- * @param mq the message queue object
- * @param buffer the message
- * @param size the size of buffer
- * @param timeout the waiting time
+ * @param    size is the length of the message(Unit: Byte).
  *
- * @return the error code
+ * @param    timeout is a timeout period (unit: an OS tick).
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the
+ *           operation is successful. If the return value is any other values,
+ *           it means that the messagequeue detach failed.
+ *
+ * @warning  This function can be called in interrupt context and thread
+ * context.
  */
 rt_err_t rt_mq_send_wait(rt_mq_t     mq,
                          const void *buffer,
@@ -2298,15 +2879,28 @@ rt_err_t rt_mq_send_wait(rt_mq_t     mq,
 }
 RTM_EXPORT(rt_mq_send_wait)
 
+
 /**
- * This function will send a message to message queue object, if there are
- * threads suspended on message queue object, it will be waked up.
+ * @brief    This function will send a message to the messagequeue object.
+ *           If there is a thread suspended on the messagequeue, the thread will be resumed.
+ *
+ * @note     When using this function to send a message, if the messagequeue is fully used,
+ *           the current thread will wait for a timeout.
+ *           By contrast, when the messagequeue is fully used, the rt_mq_send_wait() function will
+ *           return an error code immediately without waiting.
+ *
+ * @see      rt_mq_send_wait()
+ *
+ * @param    mq is a pointer to the messagequeue object to be sent.
+ *
+ * @param    buffer is the content of the message.
+ *
+ * @param    size is the length of the message(Unit: Byte).
  *
- * @param mq the message queue object
- * @param buffer the message
- * @param size the size of buffer
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the messagequeue detach failed.
  *
- * @return the error code
+ * @warning  This function can be called in interrupt context and thread context.
  */
 rt_err_t rt_mq_send(rt_mq_t mq, const void *buffer, rt_size_t size)
 {
@@ -2314,16 +2908,24 @@ rt_err_t rt_mq_send(rt_mq_t mq, const void *buffer, rt_size_t size)
 }
 RTM_EXPORT(rt_mq_send);
 
+
 /**
- * This function will send an urgent message to message queue object, which
- * means the message will be inserted to the head of message queue. If there
- * are threads suspended on message queue object, it will be waked up.
+ * @brief    This function will send an urgent message to the messagequeue object.
+ *
+ * @note     This function is almost the same as the rt_mq_send() function. The only difference is that
+ *           when sending an urgent message, the message is placed at the head of the messagequeue so that
+ *           the recipient can receive the urgent message first.
+ *
+ * @see      rt_mq_send()
+ *
+ * @param    mq is a pointer to the messagequeue object to be sent.
  *
- * @param mq the message queue object
- * @param buffer the message
- * @param size the size of buffer
+ * @param    buffer is the content of the message.
  *
- * @return the error code
+ * @param    size is the length of the message(Unit: Byte).
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the mailbox detach failed.
  */
 rt_err_t rt_mq_urgent(rt_mq_t mq, const void *buffer, rt_size_t size)
 {
@@ -2406,17 +3008,25 @@ rt_err_t rt_mq_urgent(rt_mq_t mq, const void *buffer, rt_size_t size)
 }
 RTM_EXPORT(rt_mq_urgent);
 
+
 /**
- * This function will receive a message from message queue object, if there is
- * no message in message queue object, the thread shall wait for a specified
- * time.
+ * @brief    This function will receive a message from message queue object,
+ *           if there is no message in messagequeue object, the thread shall wait for a specified time.
+ *
+ * @note     Only when there is mail in the mailbox, the receiving thread can get the mail immediately and return RT_EOK,
+ *           otherwise the receiving thread will be suspended until timeout.
+ *           If the mail is not received within the specified time, it will return -RT_ETIMEOUT.
+ *
+ * @param    mq is a pointer to the messagequeue object to be received.
  *
- * @param mq the message queue object
- * @param buffer the received message will be saved in
- * @param size the size of buffer
- * @param timeout the waiting time
+ * @param    buffer is the content of the message.
  *
- * @return the error code
+ * @param    size is the length of the message(Unit: Byte).
+ *
+ * @param    timeout is a timeout period (unit: an OS tick).
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that the mailbox release failed.
  */
 rt_err_t rt_mq_recv(rt_mq_t    mq,
                     void      *buffer,
@@ -2568,15 +3178,20 @@ rt_err_t rt_mq_recv(rt_mq_t    mq,
 }
 RTM_EXPORT(rt_mq_recv);
 
+
 /**
- * This function can get or set some extra attributions of a message queue
- * object.
+ * @brief    This function will set some extra attributions of a messagequeue object.
+ *
+ * @note     Currently this function only supports the RT_IPC_CMD_RESET command to reset the messagequeue.
  *
- * @param mq the message queue object
- * @param cmd the execution command
- * @param arg the execution argument
+ * @param    mq is a pointer to a messagequeue object.
  *
- * @return the error code
+ * @param    cmd is a command used to configure some attributions of the messagequeue.
+ *
+ * @param    arg is the argument of the function to execute the command.
+ *
+ * @return   Return the operation status. When the return value is RT_EOK, the operation is successful.
+ *           If the return value is any other values, it means that this function failed to execute.
  */
 rt_err_t rt_mq_control(rt_mq_t mq, int cmd, void *arg)
 {
@@ -2628,6 +3243,8 @@ rt_err_t rt_mq_control(rt_mq_t mq, int cmd, void *arg)
     return -RT_ERROR;
 }
 RTM_EXPORT(rt_mq_control);
+
+/**@}*/
 #endif /* RT_USING_MESSAGEQUEUE */
 
 /**@}*/