【doc】update completion.c comments

1 files changed, 15 insertions, 11 deletions

diff --git a/components/drivers/src/completion.c b/components/drivers/src/completion.c
index 37fa514613..09f51bb9df 100644
--- a/components/drivers/src/completion.c
+++ b/components/drivers/src/completion.c
@@ -6,6 +6,7 @@
  * Change Logs:
  * Date           Author       Notes
  * 2012-09-30     Bernard      first version.
+ * 2021-08-18     chenyingchun add comments
  */
 
 #include <rthw.h>
@@ -16,9 +17,9 @@
 #define RT_UNCOMPLETED  0
 
 /**
- * @brief initialize the completion object
+ * @brief This function will initialize a completion object.
  *
- * @param completion the point of completion object
+ * @param completion is a pointer to a completion object.
  */
 void rt_completion_init(struct rt_completion *completion)
 {
@@ -33,17 +34,20 @@ void rt_completion_init(struct rt_completion *completion)
 RTM_EXPORT(rt_completion_init);
 
 /**
- * @brief waitting for the completion done
- *        NOTE: We should not use this api when
+ * @brief This function will wait for a completion, if the completion is unavailable, the thread shall wait for
+ *        the completion up to a specified time.
  *
- * @param completion the point of completion object
- * @param timeout    is a timeout period (unit: an OS tick). If the completion is unavailable, the thread will wait for
- *                   the completion 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
- *                   completion is unavailable, the thread will be waitting forever.
+ * @param completion is a pointer to a completion object.
+ *
+ * @param timeout is a timeout period (unit: an OS ticks). If the completion is unavailable, the thread will wait for
+ *                the completion done 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
+ *                completion 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 completion wait failed.
+ *
+ * @warning This function can ONLY be called in the thread context. It MUST NOT BE called in interrupt context.
  */
 rt_err_t rt_completion_wait(struct rt_completion *completion,
                             rt_int32_t            timeout)
@@ -113,9 +117,9 @@ __exit:
 RTM_EXPORT(rt_completion_wait);
 
 /**
- * @brief indicate the completion has done
+ * @brief This function indicate a completion has done.
  *
- * @param completion the point of completion object
+ * @param completion is a pointer to a completion object.
  */
 void rt_completion_done(struct rt_completion *completion)
 {