add waitqueue.c function annotation

1 files changed, 45 insertions, 0 deletions

diff --git a/components/drivers/src/waitqueue.c b/components/drivers/src/waitqueue.c
index 7fe75a51ba..ee0819990e 100644
--- a/components/drivers/src/waitqueue.c
+++ b/components/drivers/src/waitqueue.c
@@ -15,6 +15,13 @@
 #include <rtdevice.h>
 #include <rtservice.h>
 
+/**
+ * @brief    This function will insert a node to the wait queue.
+ * 
+ * @param    queue is a pointer to the wait queue.
+ * 
+ * @param    node is a pointer to the node to be inserted.
+ */
 void rt_wqueue_add(rt_wqueue_t *queue, struct rt_wqueue_node *node)
 {
     rt_base_t level;
@@ -24,6 +31,13 @@ void rt_wqueue_add(rt_wqueue_t *queue, struct rt_wqueue_node *node)
     rt_hw_interrupt_enable(level);
 }
 
+/**
+ * @brief    This function will remove a node from the wait queue.
+ * 
+ * @param    queue is a pointer to the wait queue.
+ * 
+ * @param    node is a pointer to the node to be removed.
+ */
 void rt_wqueue_remove(struct rt_wqueue_node *node)
 {
     rt_base_t level;
@@ -33,11 +47,30 @@ void rt_wqueue_remove(struct rt_wqueue_node *node)
     rt_hw_interrupt_enable(level);
 }
 
+/**
+ * @brief    This function is the default wakeup function, but it actually don't do anything,
+ *           just always return 0, user should define their own wakeup function.
+ * 
+ * @param    queue is a pointer to the wait queue.
+ * 
+ * @param    key is the wakeup condition.
+ * 
+ * @return   always return 0.
+ */
 int __wqueue_default_wake(struct rt_wqueue_node *wait, void *key)
 {
     return 0;
 }
 
+/**
+ * @brief    This function will wake up a pending thread on the specified waiting queue that meets the conditions.
+ * 
+ * @param    queue is a pointer to the wait queue.
+ * 
+ * @param    key is the wakeup conditions, but it is not effective now, because
+ *           default wakeup function always return 0.
+ *           If user wants to use it, user should define their own wakeup function.
+ */
 void rt_wqueue_wakeup(rt_wqueue_t *queue, void *key)
 {
     rt_base_t level;
@@ -74,6 +107,18 @@ void rt_wqueue_wakeup(rt_wqueue_t *queue, void *key)
         rt_schedule();
 }
 
+/**
+ * @brief    This function will join a thread to the specified waiting queue, the thread will holds a wait or
+ *           timeout return on the specified wait queue.
+ * 
+ * @param    queue is a pointer to the wait queue.
+ * 
+ * @param    condition is parameters compatible with POSIX standard interface (currently meaningless, just pass in 0).
+ * 
+ * @param    msec is the timeout value, unit is millisecond.
+ * 
+ * @return   Return 0 if the thread is woken up.
+ */
 int rt_wqueue_wait(rt_wqueue_t *queue, int condition, int msec)
 {
     int tick;