Reformatted doxygen tags into the kernel sources to make them more readable.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1567 35acf78f-673a-0410-8e92-d51de3d6d3f4

1 files changed, 54 insertions, 57 deletions

diff --git a/os/kernel/src/chschd.c b/os/kernel/src/chschd.c
index 5b4d18133..5bd016226 100644
--- a/os/kernel/src/chschd.c
+++ b/os/kernel/src/chschd.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chschd.c
- * @brief Scheduler code.
+ * @file    chschd.c
+ * @brief   Scheduler code.
+ *
  * @addtogroup scheduler
  * @{
  */
@@ -27,14 +28,13 @@
 #include "ch.h"
 
 /**
- * @brief Ready list header.
+ * @brief   Ready list header.
  */
 ReadyList rlist;
 
 /**
- * @brief Scheduler initialization.
- *
- * @note Internally invoked by the @p chSysInit().
+ * @brief   Scheduler initialization.
+ * @note    Internally invoked by the @p chSysInit(), not an API.
  */
 void scheduler_init(void) {
 
@@ -49,12 +49,12 @@ void scheduler_init(void) {
 }
 
 /**
- * @brief Inserts a thread in the Ready List.
+ * @brief   Inserts a thread in the Ready List.
+ * @note    The function does not reschedule, the @p chSchRescheduleS() should
+ *          be called soon after.
  *
- * @param[in] tp the Thread to be made ready
- * @return The Thread pointer.
- * @note The function does not reschedule, the @p chSchRescheduleS() should
- *       be called soon after.
+ * @param[in] tp        the Thread to be made ready
+ * @return              The Thread pointer.
  */
 #if CH_OPTIMIZE_SPEED
 /* NOTE: it is inlined in this module only.*/
@@ -76,11 +76,11 @@ Thread *chSchReadyI(Thread *tp) {
 }
 
 /**
- * @brief Puts the current thread to sleep into the specified state.
+ * @brief   Puts the current thread to sleep into the specified state.
  * @details The thread goes into a sleeping state. The @ref thread_states are
  *          described into @p threads.h.
  *
- * @param[in] newstate the new thread state
+ * @param[in] newstate  the new thread state
  */
 void chSchGoSleepS(tstate_t newstate) {
   Thread *otp;
@@ -121,24 +121,24 @@ static void wakeup(void *p) {
 }
 
 /**
- * @brief Puts the current thread to sleep into the specified state with
- *        timeout specification.
+ * @brief   Puts the current thread to sleep into the specified state with
+ *          timeout specification.
  * @details The thread goes into a sleeping state, if it is not awakened
  *          explicitly within the specified timeout then it is forcibly
  *          awakened with a @p RDY_TIMEOUT low level message. The @ref
  *          thread_states are described into @p threads.h.
  *
- * @param[in] newstate the new thread state
- * @param[in] time the number of ticks before the operation timeouts, the
- *                 special values are handled as follow:
- *                 - @a TIME_INFINITE the thread enters an infinite sleep
- *                   state, this is equivalent to invoking @p chSchGoSleepS()
- *                   but, of course, less efficient.
- *                 - @a TIME_IMMEDIATE this value is accepted but interpreted
- *                   as a normal time specification not as an immediate timeout
- *                   specification.
- *                 .
- * @return The wakeup message.
+ * @param[in] newstate  the new thread state
+ * @param[in] time      the number of ticks before the operation timeouts, the
+ *                      special values are handled as follow:
+ *                      - @a TIME_INFINITE the thread enters an infinite sleep
+ *                        state, this is equivalent to invoking
+ *                        @p chSchGoSleepS() but, of course, less efficient.
+ *                      - @a TIME_IMMEDIATE this value is accepted but
+ *                        interpreted as a normal time specification not as an
+ *                        immediate timeout specification.
+ *                      .
+ * @return              The wakeup message.
  * @retval RDY_TIMEOUT if a timeout occurs.
  */
 msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {
@@ -157,24 +157,25 @@ msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {
 }
 
 /**
- * @brief Wakes up a thread.
+ * @brief   Wakes up a thread.
  * @details The thread is inserted into the ready list or immediately made
  *          running depending on its relative priority compared to the current
  *          thread.
+ * @note    It is equivalent to a @p chSchReadyI() followed by a
+ *          @p chSchRescheduleS() but much more efficient.
+ * @note    The function assumes that the current thread has the highest
+ *          priority.
  *
- * @param[in] ntp the Thread to be made ready
- * @param[in] msg message to the awakened thread
- * @note It is equivalent to a @p chSchReadyI() followed by a
- *       @p chSchRescheduleS() but much more efficient.
- * @note The function assumes that the current thread has the highest priority
+ * @param[in] ntp       the Thread to be made ready
+ * @param[in] msg       message to the awakened thread
  */
 void chSchWakeupS(Thread *ntp, msg_t msg) {
 
   ntp->p_u.rdymsg = msg;
   /* If the waken thread has a not-greater priority than the current
-   * one then it is just inserted in the ready list else it made
-   * running immediately and the invoking thread goes in the ready
-   * list instead.*/
+     one then it is just inserted in the ready list else it made
+     running immediately and the invoking thread goes in the ready
+     list instead.*/
   if (ntp->p_prio <= currp->p_prio)
     chSchReadyI(ntp);
   else {
@@ -190,10 +191,9 @@ void chSchWakeupS(Thread *ntp, msg_t msg) {
 }
 
 /**
- * @brief Switches to the first thread on the runnable queue.
- *
- * @note It is intended to be called if @p chSchRescRequiredI() evaluates to
- *       @p TRUE.
+ * @brief   Switches to the first thread on the runnable queue.
+ * @note    It is intended to be called if @p chSchRescRequiredI() evaluates
+ *          to @p TRUE.
  */
 void chSchDoRescheduleI(void) {
 
@@ -209,7 +209,7 @@ void chSchDoRescheduleI(void) {
 }
 
 /**
- * @brief Performs a reschedulation if a higher priority thread is runnable.
+ * @brief   Performs a reschedulation if a higher priority thread is runnable.
  * @details If a thread with a higher priority than the current thread is in
  *          the ready list then make the higher priority thread running.
  */
@@ -220,34 +220,33 @@ void chSchRescheduleS(void) {
 }
 
 /**
- * @brief Evaluates if a reschedulation is required.
+ * @brief   Evaluates if a reschedulation is required.
  * @details The decision is taken by comparing the relative priorities and
  *          depending on the state of the round robin timeout counter.
+ * @note    This function is meant to be used in the timer interrupt handler
+ *          where @p chVTDoTickI() is invoked.
  *
- * @retval TRUE if there is a thread that should go in running state.
- * @retval FALSE if a reschedulation is not required.
- *
- * @note This function is meant to be used in the timer interrupt handler
- *       where @p chVTDoTickI() is invoked.
+ * @retval TRUE         if there is a thread that should go in running state.
+ * @retval FALSE        if a reschedulation is not required.
  */
 bool_t chSchIsRescRequiredExI(void) {
   tprio_t p1 = firstprio(&rlist.r_queue);
   tprio_t p2 = currp->p_prio;
 #if CH_TIME_QUANTUM > 0
   /* If the running thread has not reached its time quantum, reschedule only
-   * if the first thread on the ready queue has a higher priority.
-   * Otherwise, if the running thread has used up its time quantum, reschedule
-   * if the first thread on the ready queue has equal or higher priority.*/
+     if the first thread on the ready queue has a higher priority.
+     Otherwise, if the running thread has used up its time quantum, reschedule
+     if the first thread on the ready queue has equal or higher priority.*/
   return rlist.r_preempt ? p1 > p2 : p1 >= p2;
 #else
-  /* If the round robin feature is not enabled then performs a simpler
-   * comparison.*/
+  /* If the round robin preemption feature is not enabled then performs a
+     simpler comparison.*/
   return p1 > p2;
 #endif
 }
 
 /**
- * @brief Yields the time slot.
+ * @brief   Yields the time slot.
  * @details Yields the CPU control to the next thread in the ready list with
  *          equal priority, if any.
  */
@@ -257,11 +256,9 @@ void chSchDoYieldS(void) {
     Thread *cp = (Thread *)&rlist.r_queue;
     Thread *otp = currp;
 
-    /*
-     * Note, the following insertion code works because we know that on the
-     * ready list there is at least one thread with priority equal or higher
-     * than the current one.
-     */
+    /* Note, the following insertion code works because we know that on the
+       ready list there is at least one thread with priority equal or higher
+       than the current one.*/
     otp->p_state = THD_STATE_READY;
     do {
       cp = cp->p_prev;