[ringbuffer] 添加 ringbuffer 的接口注释

components/drivers/include/ipc/ringbuffer.h

@@ -5,6 +5,7 @@
  *
  * Change Logs:
  * Date           Author       Notes
+ * 2021-08-14     Jackistang   add commets for function inferface.
  */
 #ifndef RINGBUFFER_H__
 #define RINGBUFFER_H__
@@ -80,6 +81,13 @@ struct rt_ringbuffer* rt_ringbuffer_create(rt_uint16_t length);
 void rt_ringbuffer_destroy(struct rt_ringbuffer *rb);
 #endif
 
+/**
+ * @brief Get buffer size of the ringbuffer object.
+ * 
+ * @param rb        A pointer to the ringbuffer object.
+ * 
+ * @return  Buffer size.
+ */
 rt_inline rt_uint16_t rt_ringbuffer_get_size(struct rt_ringbuffer *rb)
 {
     RT_ASSERT(rb != RT_NULL);

components/drivers/include/ipc/workqueue.h

@@ -6,6 +6,7 @@
  * Change Logs:
  * Date           Author       Notes
  * 2021-08-01     Meco Man     remove rt_delayed_work_init() and rt_delayed_work structure
+ * 2021-08-14     Jackistang   add commets for rt_work_init()
  */
 #ifndef WORKQUEUE_H__
 #define WORKQUEUE_H__

components/drivers/src/ringbuffer.c

@@ -9,6 +9,7 @@
  * 2013-05-08     Grissiom     reimplement
  * 2016-08-18     heyuanjie    add interface
  * 2021-07-20     arminker     fix write_index bug in function rt_ringbuffer_put_force
+ * 2021-08-14     Jackistang   add commets for function inferface.
  */
 
 #include <rtthread.h>
@@ -27,6 +28,13 @@ rt_inline enum rt_ringbuffer_state rt_ringbuffer_status(struct rt_ringbuffer *rb
     return RT_RINGBUFFER_HALFFULL;
 }
 
+/**
+ * @brief Init a ringbuffer object with a given buffer.
+ * 
+ * @param rb        A pointer to the ringbuffer object.
+ * @param pool      A pointer to the buffer.
+ * @param size      Size of the buffer in bytes.
+ */
 void rt_ringbuffer_init(struct rt_ringbuffer *rb,
                         rt_uint8_t           *pool,
                         rt_int16_t            size)
@@ -45,7 +53,13 @@ void rt_ringbuffer_init(struct rt_ringbuffer *rb,
 RTM_EXPORT(rt_ringbuffer_init);
 
 /**
- * put a block of data into ring buffer
+ * @brief Put a block of data into the ringbuffer. If the size of ringbuffer is not enough, it will discard out-of-range data.
+ * 
+ * @param rb            A pointer to the ringbuffer 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 ringbuffer actually.
  */
 rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb,
                             const rt_uint8_t     *ptr,
@@ -92,9 +106,13 @@ rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb,
 RTM_EXPORT(rt_ringbuffer_put);
 
 /**
- * put a block of data into ring buffer
+ * @brief Put a block of data into the ringbuffer. If the size of ringbuffer is not enough, it will overwrite the existing data in the ringbuffer.
- *
+ * 
- * When the buffer is full, it will discard the old data.
+ * @param rb            A pointer to the ringbuffer 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 ringbuffer actually.
  */
 rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb,
                             const rt_uint8_t     *ptr,
@@ -149,7 +167,13 @@ rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb,
 RTM_EXPORT(rt_ringbuffer_put_force);
 
 /**
- *  get data from ring buffer
+ * @brief Get a block of data from the ringbuffer.
+ * 
+ * @param rb            A pointer to the ringbuffer.
+ * @param ptr           A pointer to the data buffer.
+ * @param length        The size of data we want to read from the ringbuffer.
+ * 
+ * @return Return the size of data we read from the ringbuffer actually.
  */
 rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb,
                             rt_uint8_t           *ptr,
@@ -198,6 +222,15 @@ RTM_EXPORT(rt_ringbuffer_get);
 /**
  *  peak data from ring buffer
  */
+
+/**
+ * @brief Peak data from the ringbuffer.
+ * 
+ * @param rb        A pointer to the ringbuffer.
+ * @param ptr       When this function return, *ptr is a pointer to the first character of ringbuffer.
+ * 
+ * @return Return the size of ringbuffer.
+ */
 rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr)
 {
     RT_ASSERT(rb != RT_NULL);
@@ -230,7 +263,12 @@ rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr)
 RTM_EXPORT(rt_ringbuffer_peak);
 
 /**
- * put a character into ring buffer
+ * @brief Put a character into the ringbuffer. If ringbuffer is full, This operation will fail.
+ * 
+ * @param rb        A pointer to the ringbuffer object.
+ * @param ch        A character to be put into the ringbuffer.
+ * 
+ * @return Return the size in bytes put into the ringbuffer. If return 0, it means the ringbuffer if full. If return 1, it means success.
  */
 rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch)
 {
@@ -258,9 +296,12 @@ rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch)
 RTM_EXPORT(rt_ringbuffer_putchar);
 
 /**
- * put a character into ring buffer
+ * @brief Put a character into the ringbuffer. If ringbuffer is full, it will discard one old data and put into a new data.
- *
+ * 
- * When the buffer is full, it will discard one old data.
+ * @param rb        A pointer to the ringbuffer object.
+ * @param ch        A character to be put into the ringbuffer.
+ * 
+ * @return Return the size in bytes put into the ringbuffer. Always return 1.
  */
 rt_size_t rt_ringbuffer_putchar_force(struct rt_ringbuffer *rb, const rt_uint8_t ch)
 {
@@ -297,6 +338,16 @@ RTM_EXPORT(rt_ringbuffer_putchar_force);
 /**
  * get a character from a ringbuffer
  */
+
+/**
+ * @brief Get a character from the ringbuffer.
+ * 
+ * @param rb        The pointer to ringbuffer object.
+ * @param ch        The buffer to store character read from ringbuffer.
+ * 
+ * @return 0    Ringbuffer is empty.
+ * @return 1    Success
+ */
 rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch)
 {
     RT_ASSERT(rb != RT_NULL);
@@ -323,7 +374,11 @@ rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch)
 RTM_EXPORT(rt_ringbuffer_getchar);
 
 /**
- * get the size of data in rb
+ * @brief Get the size of data in the ringbuffer in bytes.
+ * 
+ * @param rb        The pointer to ringbuffer object.
+ * 
+ * @return Return the size of data in the ringbuffer in bytes.
  */
 rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb)
 {
@@ -344,7 +399,9 @@ rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb)
 RTM_EXPORT(rt_ringbuffer_data_len);
 
 /**
- * empty the rb
+ * @brief Reset the ringbuffer object, and clear all contents in the buffer.
+ * 
+ * @param rb        A pointer to the ringbuffer object.
  */
 void rt_ringbuffer_reset(struct rt_ringbuffer *rb)
 {
@@ -359,6 +416,13 @@ RTM_EXPORT(rt_ringbuffer_reset);
 
 #ifdef RT_USING_HEAP
 
+/**
+ * @brief Create a ringbuffer object with a given size.
+ * 
+ * @param size      Size of the buffer in bytes.
+ * 
+ * @return Return a pointer to ringbuffer object. When the return value is RT_NULL, it means the creation failed.
+ */
 struct rt_ringbuffer* rt_ringbuffer_create(rt_uint16_t size)
 {
     struct rt_ringbuffer *rb;
@@ -386,6 +450,11 @@ exit:
 }
 RTM_EXPORT(rt_ringbuffer_create);
 
+/**
+ * @brief Destroy a ringbuffer object, which is created by rt_ringbuffer_create() .
+ * 
+ * @param rb        A pointer to the ringbuffer object.
+ */
 void rt_ringbuffer_destroy(struct rt_ringbuffer *rb)
 {
     RT_ASSERT(rb != RT_NULL);

components/drivers/src/workqueue.c

@@ -7,6 +7,7 @@
  * Date           Author       Notes
  * 2017-02-27     Bernard      fix the re-work issue.
  * 2021-08-01     Meco Man     remove rt_delayed_work_init()
+ * 2021-08-14     Jackistang   add commets for function interface.
  */
 
 #include <rthw.h>