修改 ringbuffer 和 workqueue 注释的语法

4 files changed, 56 insertions, 54 deletions

diff --git a/components/drivers/include/ipc/ringbuffer.h b/components/drivers/include/ipc/ringbuffer.h
index da68c5c1fa..7da50225b3 100644
--- a/components/drivers/include/ipc/ringbuffer.h
+++ b/components/drivers/include/ipc/ringbuffer.h
@@ -82,7 +82,7 @@ void rt_ringbuffer_destroy(struct rt_ringbuffer *rb);
 #endif
 
 /**
- * @brief Get buffer size of the ring buffer object.
+ * @brief Get the buffer size of the ring buffer object.
  *
  * @param rb        A pointer to the ring buffer object.
  *
diff --git a/components/drivers/include/ipc/workqueue.h b/components/drivers/include/ipc/workqueue.h
index 70744ad668..776709a8ab 100644
--- a/components/drivers/include/ipc/workqueue.h
+++ b/components/drivers/include/ipc/workqueue.h
@@ -72,8 +72,8 @@ rt_err_t rt_work_cancel(struct rt_work *work);
  * @brief Initialize a work item, binding with a callback function.
  *
  * @param work          A pointer to the work item object.
- * @param work_func     A callback function will be called when this work item is executed.
- * @param work_data     A user data passed to the callback function as it's second parameter.
+ * @param work_func     A callback function that will be called when this work item is executed.
+ * @param work_data     A user data passed to the callback function as the second parameter.
  */
 rt_inline void rt_work_init(struct rt_work *work, void (*work_func)(struct rt_work *work, void *work_data),
                             void *work_data)
diff --git a/components/drivers/src/ringbuffer.c b/components/drivers/src/ringbuffer.c
index 417982a1b7..a8233a7555 100644
--- a/components/drivers/src/ringbuffer.c
+++ b/components/drivers/src/ringbuffer.c
@@ -29,11 +29,11 @@ rt_inline enum rt_ringbuffer_state rt_ringbuffer_status(struct rt_ringbuffer *rb
 }
 
 /**
- * @brief Initialize a ring buffer object with a given buffer.
+ * @brief Initialize the ring buffer object with the given buffer.
  *
  * @param rb        A pointer to the ring buffer object.
  * @param pool      A pointer to the buffer.
- * @param size      Size of the buffer in bytes.
+ * @param size      The size of the buffer in bytes.
  */
 void rt_ringbuffer_init(struct rt_ringbuffer *rb,
                         rt_uint8_t           *pool,
@@ -53,13 +53,13 @@ void rt_ringbuffer_init(struct rt_ringbuffer *rb,
 RTM_EXPORT(rt_ringbuffer_init);
 
 /**
- * @brief Put a block of data into the ring buffer. If the size of ring buffer is not enough, it will discard out-of-range data.
+ * @brief Put a block of data into the ring buffer. If the capacity of ring buffer is insufficient, it will discard out-of-range data.
  *
  * @param rb            A pointer to the ring buffer object.
  * @param ptr           A pointer to the data buffer.
  * @param length        The size of data in bytes.
  *
- * @return Return the size in bytes put into the ring buffer actually.
+ * @return Return the data size we put into the ring buffer.
  */
 rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb,
                             const rt_uint8_t     *ptr,
@@ -106,13 +106,13 @@ rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb,
 RTM_EXPORT(rt_ringbuffer_put);
 
 /**
- * @brief Put a block of data into the ring buffer. If the size of ring buffer is not enough, it will overwrite the existing data in the ring buffer.
+ * @brief Put a block of data into the ring buffer. If the capacity of ring buffer is insufficient, it will overwrite the existing data in the ring buffer.
  *
  * @param rb            A pointer to the ring buffer object.
  * @param ptr           A pointer to the data buffer.
  * @param length        The size of data in bytes.
  *
- * @return Return the byte size of the data actually put into the ring buffer.
+ * @return Return the data size we put into the ring buffer.
  */
 rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb,
                             const rt_uint8_t     *ptr,
@@ -171,9 +171,9 @@ RTM_EXPORT(rt_ringbuffer_put_force);
  *
  * @param rb            A pointer to the ring buffer.
  * @param ptr           A pointer to the data buffer.
- * @param length        The size of data we want to read from the ring buffer.
+ * @param length        The size of the data we want to read from the ring buffer.
  *
- * @return Return the data size that we read from the ring buffer.
+ * @return Return the data size we read from the ring buffer.
  */
 rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb,
                             rt_uint8_t           *ptr,
@@ -220,12 +220,14 @@ rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb,
 RTM_EXPORT(rt_ringbuffer_get);
 
 /**
- * @brief Peak data from the ring buffer.
+ * @brief Get the first readable byte of the ring buffer.
  *
  * @param rb        A pointer to the ringbuffer.
  * @param ptr       When this function return, *ptr is a pointer to the first readable byte of the ring buffer.
  *
- * @return Return the size of ring buffer.
+ * @note It is recommended to read only one byte, otherwise it may cause buffer overflow.
+ *
+ * @return Return the size of the ring buffer.
  */
 rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr)
 {
@@ -262,9 +264,9 @@ RTM_EXPORT(rt_ringbuffer_peak);
  * @brief Put a byte into the ring buffer. If ring buffer is full, this operation will fail.
  *
  * @param rb        A pointer to the ring buffer object.
- * @param ch        A byte to be put into the ring buffer.
+ * @param ch        A byte put into the ring buffer.
  *
- * @return Return the size in bytes put into the ring buffer. The ring buffer is full if returns 0. Otherwise, it will return 1.
+ * @return Return the data size we put into the ring buffer. The ring buffer is full if returns 0. Otherwise, it will return 1.
  */
 rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch)
 {
@@ -292,12 +294,12 @@ rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch)
 RTM_EXPORT(rt_ringbuffer_putchar);
 
 /**
- * @brief Put a byte into the ring buffer. If ring buffer is full, it will discard one old data and put into a new data.
+ * @brief Put a byte into the ring buffer. If ring buffer is full, it will discard an old data and put into a new data.
  *
  * @param rb        A pointer to the ring buffer object.
- * @param ch        A byte to be put into the ring buffer.
+ * @param ch        A byte put into the ring buffer.
  *
- * @return Return the size in bytes put into the ring buffer. Always return 1.
+ * @return Return the data size we put into the ring buffer. Always return 1.
  */
 rt_size_t rt_ringbuffer_putchar_force(struct rt_ringbuffer *rb, const rt_uint8_t ch)
 {
@@ -334,10 +336,10 @@ RTM_EXPORT(rt_ringbuffer_putchar_force);
 /**
  * @brief Get a byte from the ring buffer.
  *
- * @param rb        The pointer to ring buffer object.
- * @param ch        The buffer to store byte read from ring buffer.
+ * @param rb        The pointer to the ring buffer object.
+ * @param ch        A pointer to the buffer, used to store one byte.
  *
- * @return 0    ring buffer is empty.
+ * @return 0    The ring buffer is empty.
  * @return 1    Success
  */
 rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch)
@@ -368,7 +370,7 @@ RTM_EXPORT(rt_ringbuffer_getchar);
 /**
  * @brief Get the size of data in the ring buffer in bytes.
  *
- * @param rb        The pointer to ring buffer object.
+ * @param rb        The pointer to the ring buffer object.
  *
  * @return Return the size of data in the ring buffer in bytes.
  */
@@ -411,7 +413,7 @@ RTM_EXPORT(rt_ringbuffer_reset);
 /**
  * @brief Create a ring buffer object with a given size.
  *
- * @param size      Size of the buffer in bytes.
+ * @param size      The size of the buffer in bytes.
  *
  * @return Return a pointer to ring buffer object. When the return value is RT_NULL, it means the creation failed.
  */
@@ -443,7 +445,7 @@ exit:
 RTM_EXPORT(rt_ringbuffer_create);
 
 /**
- * @brief Destroy a ring buffer object, which is created by rt_ringbuffer_create() .
+ * @brief Destroy the ring buffer object, which is created by rt_ringbuffer_create() .
  *
  * @param rb        A pointer to the ring buffer object.
  */
diff --git a/components/drivers/src/workqueue.c b/components/drivers/src/workqueue.c
index 60472d9ca4..4a776ca485 100644
--- a/components/drivers/src/workqueue.c
+++ b/components/drivers/src/workqueue.c
@@ -211,13 +211,13 @@ static void _delayed_work_timeout_handler(void *parameter)
 }
 
 /**
- * @brief Create a work queue, which contains a thread.
+ * @brief Create a work queue with a thread inside.
  *
- * @param name          The name for work queue thread.
- * @param stack_size    The stack size for work queue thread.
- * @param priority      The priority for work queue thread.
+ * @param name          The name of the work queue thread.
+ * @param stack_size    The stack size of the work queue thread.
+ * @param priority      The priority of the work queue thread.
  *
- * @return Return a pointer to workqueue object. It will return RT_NULL if failed.
+ * @return Return A pointer to the workqueue object. It will return RT_NULL if failed.
  */
 struct rt_workqueue *rt_workqueue_create(const char *name, rt_uint16_t stack_size, rt_uint8_t priority)
 {
@@ -249,7 +249,7 @@ struct rt_workqueue *rt_workqueue_create(const char *name, rt_uint16_t stack_siz
 /**
  * @brief Destroy a work queue.
  *
- * @param queue         A pointer to workqueue object.
+ * @param queue         A pointer to the workqueue object.
  *
  * @return RT_EOK       Success.
  */
@@ -266,10 +266,10 @@ rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue)
 }
 
 /**
- * @brief Submit a work item to the work queue immediately.
+ * @brief Submit a work item to the work queue without delay.
  *
- * @param queue         A pointer to workqueue object.
- * @param work          A pointer to work item object.
+ * @param queue         A pointer to the workqueue object.
+ * @param work          A pointer to the work item object.
  *
  * @return RT_EOK       Success.
  * @return -RT_EBUSY    This work item is executing.
@@ -283,15 +283,15 @@ rt_err_t rt_workqueue_dowork(struct rt_workqueue *queue, struct rt_work *work)
 }
 
 /**
- * @brief Submit a work item to the work queue with a delay of time.
+ * @brief Submit a work item to the work queue with a delay.
  *
- * @param queue     A pointer to workqueue object.
- * @param work      A pointer to work item object.
- * @param time      This work item will be delayed by time (unit: an OS ticks) before it's been submitted to the work queue.
+ * @param queue     A pointer to the workqueue object.
+ * @param work      A pointer to the work item object.
+ * @param time      The delay time (unit: OS ticks) for the work item to be submitted to the work queue.
  *
  * @return RT_EOK       Success.
  * @return -RT_EBUSY    This work item is executing.
- * @return -RT_ERROR    Time is invalid.
+ * @return -RT_ERROR    The time parameter is invalid.
  */
 rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *work, rt_tick_t time)
 {
@@ -302,10 +302,10 @@ rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *wo
 }
 
 /**
- * @brief This function submit a work item to the work queue. This work item will be executed immediately after the current work item is executed.
+ * @brief Submit a work item to the work queue without delay. This work item will be executed after the current work item is executed.
  *
- * @param queue     A pointer to workqueue object.
- * @param work      A pointer to work item object.
+ * @param queue     A pointer to the workqueue object.
+ * @param work      A pointer to the work item object.
  *
  * @return RT_EOK   Success.
  */
@@ -339,8 +339,8 @@ rt_err_t rt_workqueue_critical_work(struct rt_workqueue *queue, struct rt_work *
 /**
  * @brief Cancel a work item in the work queue.
  *
- * @param queue     A pointer to workqueue object.
- * @param work      A pointer to work item object.
+ * @param queue     A pointer to the workqueue object.
+ * @param work      A pointer to the work item object.
  *
  * @return RT_EOK       Success.
  * @return -RT_EBUSY    This work item is executing.
@@ -353,10 +353,10 @@ rt_err_t rt_workqueue_cancel_work(struct rt_workqueue *queue, struct rt_work *wo
 }
 
 /**
- * @brief Cancel a work item in the work queue. If the work item is been executing now, this function will block until it is done.
+ * @brief Cancel a work item in the work queue. If the work item is executing, this function will block until it is done.
  *
- * @param queue     A pointer to workqueue object.
- * @param work      A pointer to work item object.
+ * @param queue     A pointer to the workqueue object.
+ * @param work      A pointer to the work item object.
  *
  * @return RT_EOK       Success.
  */
@@ -379,9 +379,9 @@ rt_err_t rt_workqueue_cancel_work_sync(struct rt_workqueue *queue, struct rt_wor
 }
 
 /**
- * @brief This function will cancel all work item in work queue.
+ * @brief This function will cancel all work items in work queue.
  *
- * @param queue     A pointer to workqueue object.
+ * @param queue     A pointer to the workqueue object.
  *
  * @return RT_EOK       Success.
  */
@@ -413,14 +413,14 @@ rt_err_t rt_workqueue_cancel_all_work(struct rt_workqueue *queue)
 static struct rt_workqueue *sys_workq;
 
 /**
- * @brief Submit a work item to the system work queue with a delay of time.
+ * @brief Submit a work item to the system work queue with a delay.
  *
- * @param work      A pointer to work item object.
- * @param time      This work item will be delayed by time (unit: an OS tick) before it's been submitted to system work queue.
+ * @param work      A pointer to the work item object.
+ * @param time      The delay time (unit: OS ticks) for the work item to be submitted to the work queue.
  *
  * @return RT_EOK       Success.
  * @return -RT_EBUSY    This work item is executing.
- * @return -RT_ERROR    Time is invalid.
+ * @return -RT_ERROR    The time parameter is invalid.
  */
 rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time)
 {
@@ -428,9 +428,9 @@ rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time)
 }
 
 /**
- * @brief Cancel a work item in system work queue.
+ * @brief Cancel a work item in the system work queue.
  *
- * @param work      A pointer to work item object.
+ * @param work      A pointer to the work item object.
  *
  * @return RT_EOK       Success.
  * @return -RT_EBUSY    This work item is executing.