From dc1f2631eeed552d6bf9466297315ca940ee389b Mon Sep 17 00:00:00 2001 From: ousugo Date: Tue, 23 Nov 2021 16:05:17 +0800 Subject: [PATCH 1/7] Add dataqueue.c function annotation --- components/drivers/src/dataqueue.c | 68 +++++++++++++++++++++++++++++- 1 file changed, 67 insertions(+), 1 deletion(-) diff --git a/components/drivers/src/dataqueue.c b/components/drivers/src/dataqueue.c index f32efa1849..be4883d954 100644 --- a/components/drivers/src/dataqueue.c +++ b/components/drivers/src/dataqueue.c @@ -21,6 +21,19 @@ struct rt_data_item rt_size_t data_size; }; +/** + * @brief This function will initialize a data queue.Calling this function will + * initialize the data queue control block and set the notification callback function. + * + * @param queue The data queue object + * @param size The maximum number of data in the data queue + * @param lwm Low water mark, when the number of data in the data queue is less than this value, + * will wake up the thread waiting for write data. + * @param evt_notify The notification callback function + * + * @return the operation status, RT_EOK on successful, + * RT_ENOMEM on insufficient memory allocation failed. + */ rt_err_t rt_data_queue_init(struct rt_data_queue *queue, rt_uint16_t size, @@ -32,7 +45,7 @@ rt_data_queue_init(struct rt_data_queue *queue, queue->evt_notify = evt_notify; - queue->magic = DATAQUEUE_MAGIC; + queue->magic = DATAQUEUE_MAGIC; queue->size = size; queue->lwm = lwm; @@ -54,6 +67,17 @@ rt_data_queue_init(struct rt_data_queue *queue, } RTM_EXPORT(rt_data_queue_init); +/** + * @brief This function will write data to the data queue. If the data queue is full, + * the thread will suspend for the specified amount of time. + * + * @param queue The data queue object + * @param data_ptr The buffer pointer of the data to be written + * @param size The size in bytes of the data to be written + * @param timeout The waiting time + * + * @return the operation status, RT_EOK on successful + */ rt_err_t rt_data_queue_push(struct rt_data_queue *queue, const void *data_ptr, rt_size_t data_size, @@ -153,6 +177,20 @@ __exit: } RTM_EXPORT(rt_data_queue_push); +/** + * @brief This function will pop data from the data queue. If the data queue is empty, + * the thread will suspend for the specified amount of time. + * + * @attention when the number of data in the data queue is less than lwm(low water mark), + * will wake up the thread waiting for write data. + * + * @param queue The data queue object + * @param data_ptr The buffer pointer of the data to be fetched + * @param size The size in bytes of the data to be fetched + * @param timeout The waiting time + * + * @return Operation status, RT_EOK on successful, RT_ETIMEOUT on timeout. + */ rt_err_t rt_data_queue_pop(struct rt_data_queue *queue, const void** data_ptr, rt_size_t *size, @@ -264,6 +302,15 @@ __exit: } RTM_EXPORT(rt_data_queue_pop); +/** + * @brief This function will fetching but retaining data in the data queue. + * + * @param queue The data queue object + * @param data_ptr The buffer pointer of the data to be fetched + * @param size The size in bytes of the data to be fetched + * + * @return The operation status, RT_EOK on successful + */ rt_err_t rt_data_queue_peek(struct rt_data_queue *queue, const void** data_ptr, rt_size_t *size) @@ -289,6 +336,12 @@ rt_err_t rt_data_queue_peek(struct rt_data_queue *queue, } RTM_EXPORT(rt_data_queue_peek); +/** + * @brief Reset a data queue. Calling this function will wake up all threads on the data queue + * that are hanging and waiting. + * + * @param queue The data queue object + */ void rt_data_queue_reset(struct rt_data_queue *queue) { rt_ubase_t level; @@ -362,6 +415,13 @@ void rt_data_queue_reset(struct rt_data_queue *queue) } RTM_EXPORT(rt_data_queue_reset); +/** + * @brief Deinit a data queue. + * + * @param queue The data queue object + * + * @return operation status, RT_EOK on successful. + */ rt_err_t rt_data_queue_deinit(struct rt_data_queue *queue) { rt_ubase_t level; @@ -382,6 +442,12 @@ rt_err_t rt_data_queue_deinit(struct rt_data_queue *queue) } RTM_EXPORT(rt_data_queue_deinit); +/** + * @brief This function get the number of data in the data queue. + * + * @param queue The data queue object + * @return The number of data in the data queue + */ rt_uint16_t rt_data_queue_len(struct rt_data_queue *queue) { rt_ubase_t level; From afdbee97ed139800e02441bd80efa4f8b8976aa2 Mon Sep 17 00:00:00 2001 From: ousugo Date: Tue, 23 Nov 2021 16:40:55 +0800 Subject: [PATCH 2/7] fix extra space --- components/drivers/src/dataqueue.c | 38 +++++++++++++++--------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/components/drivers/src/dataqueue.c b/components/drivers/src/dataqueue.c index be4883d954..4e51d72865 100644 --- a/components/drivers/src/dataqueue.c +++ b/components/drivers/src/dataqueue.c @@ -22,16 +22,16 @@ struct rt_data_item }; /** - * @brief This function will initialize a data queue.Calling this function will + * @brief This function will initialize a data queue.Calling this function will * initialize the data queue control block and set the notification callback function. - * + * * @param queue The data queue object * @param size The maximum number of data in the data queue * @param lwm Low water mark, when the number of data in the data queue is less than this value, * will wake up the thread waiting for write data. * @param evt_notify The notification callback function - * - * @return the operation status, RT_EOK on successful, + * + * @return the operation status, RT_EOK on successful, * RT_ENOMEM on insufficient memory allocation failed. */ rt_err_t @@ -45,7 +45,7 @@ rt_data_queue_init(struct rt_data_queue *queue, queue->evt_notify = evt_notify; - queue->magic = DATAQUEUE_MAGIC; + queue->magic = DATAQUEUE_MAGIC; queue->size = size; queue->lwm = lwm; @@ -70,13 +70,13 @@ RTM_EXPORT(rt_data_queue_init); /** * @brief This function will write data to the data queue. If the data queue is full, * the thread will suspend for the specified amount of time. - * + * * @param queue The data queue object * @param data_ptr The buffer pointer of the data to be written * @param size The size in bytes of the data to be written * @param timeout The waiting time - * - * @return the operation status, RT_EOK on successful + * + * @return the operation status, RT_EOK on successful */ rt_err_t rt_data_queue_push(struct rt_data_queue *queue, const void *data_ptr, @@ -180,15 +180,15 @@ RTM_EXPORT(rt_data_queue_push); /** * @brief This function will pop data from the data queue. If the data queue is empty, * the thread will suspend for the specified amount of time. - * + * * @attention when the number of data in the data queue is less than lwm(low water mark), * will wake up the thread waiting for write data. - * + * * @param queue The data queue object * @param data_ptr The buffer pointer of the data to be fetched * @param size The size in bytes of the data to be fetched * @param timeout The waiting time - * + * * @return Operation status, RT_EOK on successful, RT_ETIMEOUT on timeout. */ rt_err_t rt_data_queue_pop(struct rt_data_queue *queue, @@ -304,12 +304,12 @@ RTM_EXPORT(rt_data_queue_pop); /** * @brief This function will fetching but retaining data in the data queue. - * + * * @param queue The data queue object * @param data_ptr The buffer pointer of the data to be fetched * @param size The size in bytes of the data to be fetched - * - * @return The operation status, RT_EOK on successful + * + * @return The operation status, RT_EOK on successful */ rt_err_t rt_data_queue_peek(struct rt_data_queue *queue, const void** data_ptr, @@ -339,7 +339,7 @@ RTM_EXPORT(rt_data_queue_peek); /** * @brief Reset a data queue. Calling this function will wake up all threads on the data queue * that are hanging and waiting. - * + * * @param queue The data queue object */ void rt_data_queue_reset(struct rt_data_queue *queue) @@ -417,9 +417,9 @@ RTM_EXPORT(rt_data_queue_reset); /** * @brief Deinit a data queue. - * + * * @param queue The data queue object - * + * * @return operation status, RT_EOK on successful. */ rt_err_t rt_data_queue_deinit(struct rt_data_queue *queue) @@ -444,9 +444,9 @@ RTM_EXPORT(rt_data_queue_deinit); /** * @brief This function get the number of data in the data queue. - * + * * @param queue The data queue object - * @return The number of data in the data queue + * @return The number of data in the data queue */ rt_uint16_t rt_data_queue_len(struct rt_data_queue *queue) { From 2c2a1fe64ee1e03ffbac9df9ec452cc00e18df0c Mon Sep 17 00:00:00 2001 From: ousugo Date: Wed, 24 Nov 2021 14:14:45 +0800 Subject: [PATCH 3/7] Update annotation format --- components/drivers/src/dataqueue.c | 93 +++++++++++++++++------------- 1 file changed, 54 insertions(+), 39 deletions(-) diff --git a/components/drivers/src/dataqueue.c b/components/drivers/src/dataqueue.c index 4e51d72865..fcaa8f379d 100644 --- a/components/drivers/src/dataqueue.c +++ b/components/drivers/src/dataqueue.c @@ -22,17 +22,21 @@ struct rt_data_item }; /** - * @brief This function will initialize a data queue.Calling this function will - * initialize the data queue control block and set the notification callback function. + * @brief This function will initialize a data queue.Calling this function will + * initialize the data queue control block and set the notification callback function. * - * @param queue The data queue object - * @param size The maximum number of data in the data queue - * @param lwm Low water mark, when the number of data in the data queue is less than this value, - * will wake up the thread waiting for write data. - * @param evt_notify The notification callback function + * @param queue is a pointer to a data queue object. * - * @return the operation status, RT_EOK on successful, - * RT_ENOMEM on insufficient memory allocation failed. + * @param size is the maximum number of data in the data queue. + * + * @param lwm is low water mark. + * When the number of data in the data queue is less than this value,will + * wake up the thread waiting for write data. + * + * @param evt_notify is the notification callback function. + * + * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. + * When the return value is RT_ENOMEM, it means insufficient memory allocation failed. */ rt_err_t rt_data_queue_init(struct rt_data_queue *queue, @@ -68,15 +72,18 @@ rt_data_queue_init(struct rt_data_queue *queue, RTM_EXPORT(rt_data_queue_init); /** - * @brief This function will write data to the data queue. If the data queue is full, - * the thread will suspend for the specified amount of time. + * @brief This function will write data to the data queue. If the data queue is full, + * the thread will suspend for the specified amount of time. * - * @param queue The data queue object - * @param data_ptr The buffer pointer of the data to be written - * @param size The size in bytes of the data to be written - * @param timeout The waiting time + * @param queue is a pointer to a data queue object. + * . + * @param data_ptr is the buffer pointer of the data to be written. * - * @return the operation status, RT_EOK on successful + * @param size is the size in bytes of the data to be written. + * + * @param timeout is the waiting time. + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. */ rt_err_t rt_data_queue_push(struct rt_data_queue *queue, const void *data_ptr, @@ -178,18 +185,21 @@ __exit: RTM_EXPORT(rt_data_queue_push); /** - * @brief This function will pop data from the data queue. If the data queue is empty, - * the thread will suspend for the specified amount of time. + * @brief This function will pop data from the data queue. If the data queue is empty,the thread + * will suspend for the specified amount of time. * - * @attention when the number of data in the data queue is less than lwm(low water mark), - * will wake up the thread waiting for write data. + * @note when the number of data in the data queue is less than lwm(low water mark),will + * wake up the thread waiting for write data. * - * @param queue The data queue object - * @param data_ptr The buffer pointer of the data to be fetched - * @param size The size in bytes of the data to be fetched - * @param timeout The waiting time + * @param queue is a pointer to a data queue object. * - * @return Operation status, RT_EOK on successful, RT_ETIMEOUT on timeout. + * @param data_ptr is the buffer pointer of the data to be fetched. + * + * @param size is the size in bytes of the data to be fetched. + * + * @param timeout is the waiting time. + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. */ rt_err_t rt_data_queue_pop(struct rt_data_queue *queue, const void** data_ptr, @@ -303,13 +313,15 @@ __exit: RTM_EXPORT(rt_data_queue_pop); /** - * @brief This function will fetching but retaining data in the data queue. + * @brief This function will fetching but retaining data in the data queue. * - * @param queue The data queue object - * @param data_ptr The buffer pointer of the data to be fetched - * @param size The size in bytes of the data to be fetched + * @param queue is a pointer to a data queue object. * - * @return The operation status, RT_EOK on successful + * @param data_ptr is the buffer pointer of the data to be fetched. + * + * @param size is the size in bytes of the data to be fetched. + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. */ rt_err_t rt_data_queue_peek(struct rt_data_queue *queue, const void** data_ptr, @@ -337,10 +349,12 @@ rt_err_t rt_data_queue_peek(struct rt_data_queue *queue, RTM_EXPORT(rt_data_queue_peek); /** - * @brief Reset a data queue. Calling this function will wake up all threads on the data queue - * that are hanging and waiting. + * @brief This function will reset a data queue. * - * @param queue The data queue object + * @note Calling this function will wake up all threads on the data queue + * that are hanging and waiting. + * + * @param queue is a pointer to a data queue object. */ void rt_data_queue_reset(struct rt_data_queue *queue) { @@ -416,11 +430,11 @@ void rt_data_queue_reset(struct rt_data_queue *queue) RTM_EXPORT(rt_data_queue_reset); /** - * @brief Deinit a data queue. + * @brief This function will deinit a data queue. * - * @param queue The data queue object + * @param queue is a pointer to a data queue object. * - * @return operation status, RT_EOK on successful. + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. */ rt_err_t rt_data_queue_deinit(struct rt_data_queue *queue) { @@ -443,10 +457,11 @@ rt_err_t rt_data_queue_deinit(struct rt_data_queue *queue) RTM_EXPORT(rt_data_queue_deinit); /** - * @brief This function get the number of data in the data queue. + * @brief This function will get the number of data in the data queue. * - * @param queue The data queue object - * @return The number of data in the data queue + * @param queue is a pointer to a data queue object. + * + * @return Return the number of data in the data queue. */ rt_uint16_t rt_data_queue_len(struct rt_data_queue *queue) { From 1deaa8fe50949580aaba53df3f8f0b07e259e879 Mon Sep 17 00:00:00 2001 From: ousugo Date: Wed, 24 Nov 2021 14:19:25 +0800 Subject: [PATCH 4/7] Update annotation format --- components/drivers/src/dataqueue.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/drivers/src/dataqueue.c b/components/drivers/src/dataqueue.c index fcaa8f379d..d13378a507 100644 --- a/components/drivers/src/dataqueue.c +++ b/components/drivers/src/dataqueue.c @@ -188,7 +188,7 @@ RTM_EXPORT(rt_data_queue_push); * @brief This function will pop data from the data queue. If the data queue is empty,the thread * will suspend for the specified amount of time. * - * @note when the number of data in the data queue is less than lwm(low water mark),will + * @note when the number of data in the data queue is less than lwm(low water mark), will * wake up the thread waiting for write data. * * @param queue is a pointer to a data queue object. From 02ca44bf1f1f56bf9ea3864a095f48da3ad827b5 Mon Sep 17 00:00:00 2001 From: ousugo Date: Wed, 24 Nov 2021 15:21:30 +0800 Subject: [PATCH 5/7] Fix annotation grammatical mistake --- components/drivers/src/dataqueue.c | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/components/drivers/src/dataqueue.c b/components/drivers/src/dataqueue.c index d13378a507..c23c34b484 100644 --- a/components/drivers/src/dataqueue.c +++ b/components/drivers/src/dataqueue.c @@ -22,15 +22,15 @@ struct rt_data_item }; /** - * @brief This function will initialize a data queue.Calling this function will + * @brief This function will initialize the data queue.Calling this function will * initialize the data queue control block and set the notification callback function. * - * @param queue is a pointer to a data queue object. + * @param queue is a pointer to the data queue object. * * @param size is the maximum number of data in the data queue. * * @param lwm is low water mark. - * When the number of data in the data queue is less than this value,will + * When the number of data in the data queue is less than this value, this function will * wake up the thread waiting for write data. * * @param evt_notify is the notification callback function. @@ -75,7 +75,7 @@ RTM_EXPORT(rt_data_queue_init); * @brief This function will write data to the data queue. If the data queue is full, * the thread will suspend for the specified amount of time. * - * @param queue is a pointer to a data queue object. + * @param queue is a pointer to the data queue object. * . * @param data_ptr is the buffer pointer of the data to be written. * @@ -188,10 +188,10 @@ RTM_EXPORT(rt_data_queue_push); * @brief This function will pop data from the data queue. If the data queue is empty,the thread * will suspend for the specified amount of time. * - * @note when the number of data in the data queue is less than lwm(low water mark), will + * @note When the number of data in the data queue is less than lwm(low water mark), will * wake up the thread waiting for write data. * - * @param queue is a pointer to a data queue object. + * @param queue is a pointer to the data queue object. * * @param data_ptr is the buffer pointer of the data to be fetched. * @@ -313,9 +313,9 @@ __exit: RTM_EXPORT(rt_data_queue_pop); /** - * @brief This function will fetching but retaining data in the data queue. + * @brief This function will fetch but retaining data in the data queue. * - * @param queue is a pointer to a data queue object. + * @param queue is a pointer to the data queue object. * * @param data_ptr is the buffer pointer of the data to be fetched. * @@ -349,12 +349,12 @@ rt_err_t rt_data_queue_peek(struct rt_data_queue *queue, RTM_EXPORT(rt_data_queue_peek); /** - * @brief This function will reset a data queue. + * @brief This function will reset the data queue. * * @note Calling this function will wake up all threads on the data queue * that are hanging and waiting. * - * @param queue is a pointer to a data queue object. + * @param queue is a pointer to the data queue object. */ void rt_data_queue_reset(struct rt_data_queue *queue) { @@ -430,9 +430,9 @@ void rt_data_queue_reset(struct rt_data_queue *queue) RTM_EXPORT(rt_data_queue_reset); /** - * @brief This function will deinit a data queue. + * @brief This function will deinit the data queue. * - * @param queue is a pointer to a data queue object. + * @param queue is a pointer to the data queue object. * * @return Return the operation status. When the return value is RT_EOK, the operation is successful. */ @@ -459,7 +459,7 @@ RTM_EXPORT(rt_data_queue_deinit); /** * @brief This function will get the number of data in the data queue. * - * @param queue is a pointer to a data queue object. + * @param queue is a pointer to the data queue object. * * @return Return the number of data in the data queue. */ From 2ef0d40aff71d6cd8fee7af6babca689aae621a2 Mon Sep 17 00:00:00 2001 From: ousugo Date: Wed, 24 Nov 2021 21:59:37 +0800 Subject: [PATCH 6/7] Fix space --- components/drivers/src/dataqueue.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/drivers/src/dataqueue.c b/components/drivers/src/dataqueue.c index c23c34b484..1f7971a367 100644 --- a/components/drivers/src/dataqueue.c +++ b/components/drivers/src/dataqueue.c @@ -22,7 +22,7 @@ struct rt_data_item }; /** - * @brief This function will initialize the data queue.Calling this function will + * @brief This function will initialize the data queue. Calling this function will * initialize the data queue control block and set the notification callback function. * * @param queue is a pointer to the data queue object. From b329611e3547d663b7914cb5966f1a849470c264 Mon Sep 17 00:00:00 2001 From: ousugo Date: Wed, 1 Dec 2021 14:43:53 +0800 Subject: [PATCH 7/7] Update annotation --- components/drivers/src/dataqueue.c | 3 +++ 1 file changed, 3 insertions(+) diff --git a/components/drivers/src/dataqueue.c b/components/drivers/src/dataqueue.c index 1f7971a367..4e52662c44 100644 --- a/components/drivers/src/dataqueue.c +++ b/components/drivers/src/dataqueue.c @@ -84,6 +84,7 @@ RTM_EXPORT(rt_data_queue_init); * @param timeout is the waiting time. * * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * When the return value is RT_ETIMEOUT, it means the specified time out. */ rt_err_t rt_data_queue_push(struct rt_data_queue *queue, const void *data_ptr, @@ -200,6 +201,7 @@ RTM_EXPORT(rt_data_queue_push); * @param timeout is the waiting time. * * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * When the return value is RT_ETIMEOUT, it means the specified time out. */ rt_err_t rt_data_queue_pop(struct rt_data_queue *queue, const void** data_ptr, @@ -322,6 +324,7 @@ RTM_EXPORT(rt_data_queue_pop); * @param size is the size in bytes of the data to be fetched. * * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * When the return value is -RT_EEMPTY, it means the data queue is empty. */ rt_err_t rt_data_queue_peek(struct rt_data_queue *queue, const void** data_ptr,