【doc】update completion.c comments

This commit is contained in:
chenyingchun0312 2021-08-18 14:10:50 +08:00
parent 7f2aaa210c
commit a6870449ba
1 changed files with 15 additions and 11 deletions

View File

@ -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)
{