Merge pull request #5040 from yangjie11/comments

[kernel]Normalized kernel API annotation

1 files changed, 40 insertions, 36 deletions

diff --git a/src/scheduler.c b/src/scheduler.c
index bb431e2efe..6ef02f3d3c 100644
--- a/src/scheduler.c
+++ b/src/scheduler.c
@@ -58,19 +58,23 @@ static void (*rt_scheduler_switch_hook)(struct rt_thread *tid);
 /**@{*/
 
 /**
- * This function will set a hook function, which will be invoked when thread
- * switch happens.
+ * @brief This function will set a hook function, which will be invoked when thread
+ *        switch happens.
  *
- * @param hook the hook function
+ * @param hook is the hook function.
  */
-void
-rt_scheduler_sethook(void (*hook)(struct rt_thread *from, struct rt_thread *to))
+void rt_scheduler_sethook(void (*hook)(struct rt_thread *from, struct rt_thread *to))
 {
     rt_scheduler_hook = hook;
 }
 
-void
-rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid))
+/**
+ * @brief This function will set a hook function, which will be invoked when context
+ *        switch happens.
+ *
+ * @param hook is the hook function.
+ */
+void rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid))
 {
     rt_scheduler_switch_hook = hook;
 }
@@ -181,8 +185,7 @@ static struct rt_thread* _scheduler_get_highest_priority_thread(rt_ubase_t *high
 #endif /* RT_USING_SMP */
 
 /**
- * @ingroup SystemInit
- * This function will initialize the system scheduler
+ * @brief This function will initialize the system scheduler.
  */
 void rt_system_scheduler_init(void)
 {
@@ -232,9 +235,8 @@ void rt_system_scheduler_init(void)
 }
 
 /**
- * @ingroup SystemInit
- * This function will startup scheduler. It will select one thread
- * with the highest priority level, then switch to it.
+ * @brief This function will startup the scheduler. It will select one thread
+ *        with the highest priority level, then switch to it.
  */
 void rt_system_scheduler_start(void)
 {
@@ -271,12 +273,13 @@ void rt_system_scheduler_start(void)
 
 #ifdef RT_USING_SMP
 /**
- * This function will handle IPI interrupt and do a scheduling in system;
+ * @brief This function will handle IPI interrupt and do a scheduling in system.
  *
- * @param vector, the number of IPI interrupt for system scheduling
- * @param param, use RT_NULL
+ * @param vector is the number of IPI interrupt for system scheduling.
  *
- * NOTE: this function should be invoke or register as ISR in BSP.
+ * @param param is not used, and can be set to RT_NULL.
+ *
+ * @note this function should be invoke or register as ISR in BSP.
  */
 void rt_scheduler_ipi_handler(int vector, void *param)
 {
@@ -284,9 +287,9 @@ void rt_scheduler_ipi_handler(int vector, void *param)
 }
 
 /**
- * This function will perform one scheduling. It will select one thread
- * with the highest priority level in global ready queue or local ready queue,
- * then switch to it.
+ * @brief This function will perform one scheduling. It will select one thread
+ *        with the highest priority level in global ready queue or local ready queue,
+ *        then switch to it.
  */
 void rt_schedule(void)
 {
@@ -407,8 +410,8 @@ __exit:
 }
 #else
 /**
- * This function will perform one schedule. It will select one thread
- * with the highest priority level, and switch to it immediately.
+ * @brief This function will perform scheduling once. It will select one thread
+ *        with the highest priority, and switch to it immediately.
  */
 void rt_schedule(void)
 {
@@ -536,9 +539,9 @@ __exit:
 #endif /* RT_USING_SMP */
 
 /**
- * This function checks if a scheduling is needed after IRQ context. If yes,
- * it will select one thread with the highest priority level, and then switch
- * to it.
+ * @brief This function checks whether a scheduling is needed after an IRQ context switching. If yes,
+ *        it will select one thread with the highest priority level, and then switch
+ *        to it.
  */
 #ifdef RT_USING_SMP
 void rt_scheduler_do_irq_switch(void *context)
@@ -631,12 +634,13 @@ void rt_scheduler_do_irq_switch(void *context)
 }
 #endif /* RT_USING_SMP */
 
-/*
- * This function will insert a thread to system ready queue. The state of
- * thread will be set as READY and remove from suspend queue.
+/**
+ * @brief This function will insert a thread to the system ready queue. The state of
+ *        thread will be set as READY and the thread will be removed from suspend queue.
+ *
+ * @param thread is the thread to be inserted.
  *
- * @param thread the thread to be inserted
- * @note Please do not invoke this function in user application.
+ * @note  Please do not invoke this function in user application.
  */
 #ifdef RT_USING_SMP
 void rt_schedule_insert_thread(struct rt_thread *thread)
@@ -741,12 +745,12 @@ __exit:
 }
 #endif /* RT_USING_SMP */
 
-/*
- * This function will remove a thread from system ready queue.
+/**
+ * @brief This function will remove a thread from system ready queue.
  *
- * @param thread the thread to be removed
+ * @param thread is the thread to be removed.
  *
- * @note Please do not invoke this function in user application.
+ * @note  Please do not invoke this function in user application.
  */
 #ifdef RT_USING_SMP
 void rt_schedule_remove_thread(struct rt_thread *thread)
@@ -835,7 +839,7 @@ void rt_schedule_remove_thread(struct rt_thread *thread)
 #endif /* RT_USING_SMP */
 
 /**
- * This function will lock the thread scheduler.
+ * @brief This function will lock the thread scheduler.
  */
 #ifdef RT_USING_SMP
 void rt_enter_critical(void)
@@ -897,7 +901,7 @@ void rt_enter_critical(void)
 RTM_EXPORT(rt_enter_critical);
 
 /**
- * This function will unlock the thread scheduler.
+ * @brief This function will unlock the thread scheduler.
  */
 #ifdef RT_USING_SMP
 void rt_exit_critical(void)
@@ -971,7 +975,7 @@ void rt_exit_critical(void)
 RTM_EXPORT(rt_exit_critical);
 
 /**
- * Get the scheduler lock level
+ * @brief Get the scheduler lock level.
  *
  * @return the level of the scheduler lock. 0 means unlocked.
  */