From f62bd0373a21dd21e450ae9a48d9f6f4923f30b2 Mon Sep 17 00:00:00 2001
From: ousugo <dkzyxh@gmail.com>
Date: Fri, 10 Dec 2021 11:14:23 +0800
Subject: [PATCH] add waitqueue.c function annotation

---
 components/drivers/src/waitqueue.c | 45 ++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/components/drivers/src/waitqueue.c b/components/drivers/src/waitqueue.c
index 7fe75a51b..ee0819990 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;
-- 
GitLab