score misc: Score misc: Clean up Doxygen #9 (GCI 2012)

This patch is a task from GCI 2012 which improves the Doxygen
comments in the RTEMS source.

https://google-melange.appspot.com/gci/task/view/google/gci2012/7977211

9 files changed, 71 insertions, 56 deletions

diff --git a/cpukit/score/include/rtems/score/corebarrier.h b/cpukit/score/include/rtems/score/corebarrier.h
index a29780531e..7f9c5d8be5 100644
--- a/cpukit/score/include/rtems/score/corebarrier.h
+++ b/cpukit/score/include/rtems/score/corebarrier.h
@@ -121,6 +121,8 @@ typedef struct {
 }   CORE_barrier_Control;
 
 /**
+ *  @brief Initialize CORE Barrier
+ *
  *  This routine initializes the barrier based on the parameters passed.
  *
  *  @param[in] the_barrier is the barrier to initialize
@@ -157,7 +159,7 @@ void _CORE_barrier_Wait(
 
 /**
  *  @brief Manually releases the barrier
- *  
+ *
  *  This routine manually releases the barrier.  All of the threads waiting
  *  for the barrier will be readied.
  *
diff --git a/cpukit/score/include/rtems/score/coremutex.h b/cpukit/score/include/rtems/score/coremutex.h
index 01a0dd54ed..8076a376b0 100644
--- a/cpukit/score/include/rtems/score/coremutex.h
+++ b/cpukit/score/include/rtems/score/coremutex.h
@@ -18,8 +18,6 @@
 
 #ifndef _RTEMS_SCORE_COREMUTEX_H
 #define _RTEMS_SCORE_COREMUTEX_H
-
-
 /**
  *  @defgroup ScoreMutex Mutex Handler
  *
@@ -336,13 +334,11 @@ void _CORE_mutex_Seize_interrupt_blocking(
   CORE_mutex_Control  *the_mutex,
   Watchdog_Interval    timeout
 );
-
-
 /**
  *  @brief Sieze Interrupt Wrapper
  *
  *  This macro is to verify that a mutex blocking seize is
- *  performed from a safe system state.  For example, one 
+ *  performed from a safe system state.  For example, one
  *  cannot block inside an isr.
  *
  *  @return this method returns true if dispatch is in an unsafe state.
diff --git a/cpukit/score/include/rtems/score/isr.h b/cpukit/score/include/rtems/score/isr.h
index 8a0574951b..0d93d29de9 100644
--- a/cpukit/score/include/rtems/score/isr.h
+++ b/cpukit/score/include/rtems/score/isr.h
@@ -50,7 +50,7 @@ typedef void ISR_Handler;
 
 #if (CPU_SIMPLE_VECTORED_INTERRUPTS == FALSE)
 
-typedef void * ISR_Handler_entry; 
+typedef void * ISR_Handler_entry;
 
 #else
 /**
@@ -87,7 +87,7 @@ SCORE_EXTERN ISR_Handler_entry *_ISR_Vector_table;
 #endif
 
 /**
- *  @brief Initialize the ISR handler
+ *  @brief Initialize the ISR Handler
  *
  *  This routine performs the initialization necessary for the ISR handler.
  */
@@ -232,7 +232,7 @@ int _ISR_SMP_Exit(void);
   #define _ISR_Disable( _level ) \
     _ISR_Disable_on_this_core( _level );
 #endif
-  
+
 /**
  *  @brief Exits Interrupt Disable Critical Section
  *
@@ -281,6 +281,9 @@ int _ISR_SMP_Exit(void);
  *  for the specified vector.  The previous interrupt service routine is
  *  returned as old_handler.
  *
+ *  LM32 Specific Information:
+ *  XXX document implementation including references if appropriate
+ *
  *  @param[in] _vector is the vector number
  *  @param[in] _new_handler is ISR handler to install
  *  @param[in] _old_handler is a pointer to a variable which will be set
@@ -296,6 +299,9 @@ int _ISR_SMP_Exit(void);
  *
  *  This routine returns the current interrupt level.
  *
+ *  LM32 Specific Information:
+ *  XXX document implementation including references if appropriate
+ *
  *  @return This method returns the current level.
  */
 #define _ISR_Get_level() \
diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h
index 29c98a8183..6d43b39e81 100644
--- a/cpukit/score/include/rtems/score/object.h
+++ b/cpukit/score/include/rtems/score/object.h
@@ -135,8 +135,6 @@ typedef uint16_t   Objects_Maximum;
  *  the object Id.
  */
 #define OBJECTS_INDEX_START_BIT  0U
-
-
 /**
  *  This is the bit position of the starting bit of the node portion of
  *  the object Id.
@@ -525,6 +523,7 @@ Objects_Control *_Objects_Allocate(
 );
 
 /**
+ *  @brief Free Object
  *
  *  This function frees a object control block to the
  *  inactive chain of free object control blocks.
diff --git a/cpukit/score/include/rtems/score/schedulerpriority.h b/cpukit/score/include/rtems/score/schedulerpriority.h
index b8dee43fc1..f959c0e174 100644
--- a/cpukit/score/include/rtems/score/schedulerpriority.h
+++ b/cpukit/score/include/rtems/score/schedulerpriority.h
@@ -70,7 +70,7 @@ void _Scheduler_priority_Initialize(void);
 
 /**
  *  @brief Scheduler priority Block
- * 
+ *
  *  This routine removes @a the_thread from the scheduling decision,
  *  that is, removes it from the ready queue.  It performs
  *  any necessary scheduling operations including the selection of
@@ -103,6 +103,8 @@ void * _Scheduler_priority_Allocate(
 );
 
 /**
+ *  @brief Free Scheduler Priority
+ *
  *  This routine frees @a the_thread->scheduler.
  *
  *  @param[in] the_thread is the thread whose scheduler specific information
@@ -113,7 +115,7 @@ void _Scheduler_priority_Free(
 );
 
 /**
- *  @brief Update Scheduler priority 
+ *  @brief Update Scheduler priority
  *  This routine updates @a the_thread->scheduler based on @a the_scheduler
  *  structures and thread state.
  *
@@ -126,7 +128,7 @@ void _Scheduler_priority_Update(
 
 /**
  *  @brief Scheduler Priority Unblock
- * 
+ *
  *  This routine adds @a the_thread to the scheduling decision,
  *  that is, adds it to the ready queue and
  *  updates any appropriate scheduling variables, for example the heir thread.
@@ -149,7 +151,7 @@ void _Scheduler_priority_Unblock(
  *  reset is true and this is the only thread on the queue then the
  *  timeslice counter is reset.  The heir THREAD will be updated if the
  *  running is also the currently the heir.
- * 
+ *
  *  - INTERRUPT LATENCY:
  *    + ready chain
  *    + select heir
@@ -157,6 +159,8 @@ void _Scheduler_priority_Unblock(
 void _Scheduler_priority_Yield( void );
 
 /**
+ *  @brief Scheduler Priority Enqueue
+ *
  *  This routine puts @a the_thread on to the priority-based ready queue.
  *
  *  @param[in] the_thread will be enqueued at the TAIL of its priority.
@@ -179,7 +183,7 @@ void _Scheduler_priority_Enqueue_first(
 );
 
 /**
- *  @brief Removes a specific thread from scheduler  
+ *  @brief Removes a specific thread from scheduler
  *
  *  This routine removes a specific thread from the scheduler's set
  *  of ready threads.
diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h
index bb8fcb8368..502ef8e8ec 100644
--- a/cpukit/score/include/rtems/score/thread.h
+++ b/cpukit/score/include/rtems/score/thread.h
@@ -502,9 +502,9 @@ SCORE_EXTERN Thread_Control *_Thread_Allocated_fp;
  * holds a pointer to the task specific data.
  */
 SCORE_EXTERN struct _reent **_Thread_libc_reent;
-
-
 /**
+ *  @brief Initialize Thread Handler
+ *
  *  This routine performs the initialization necessary for this handler.
  */
 void _Thread_Handler_initialization(void);
@@ -524,8 +524,8 @@ void _Thread_Create_idle(void);
  *  This routine initiates multitasking.  It is invoked only as
  *  part of initialization and its invocation is the last act of
  *  the non-multitasking part of the system initialization.
- * 
- * 
+ *
+ *
  *  - INTERRUPT LATENCY:
  *    + ready chain
  *    + select heir
@@ -534,15 +534,15 @@ void _Thread_Start_multitasking( void );
 
 /**
  *  @brief Dispatch Thread
- *  
+ *
  *  This routine is responsible for transferring control of the
- *  processor from the executing thread to the heir thread. Once the 
+ *  processor from the executing thread to the heir thread. Once the
  *  heir is running an attempt is made to dispatch any ASRs.
  *  As part of this process, it is responsible for the following actions:
  *     + saving the context of the executing thread
  *     + restoring the context of the heir thread
  *     + dispatching any signals for the resulting executing thread
- 
+
  *  ALTERNATE ENTRY POINTS:
  *    void _Thread_Enable_dispatch();
  *
@@ -559,7 +559,7 @@ void _Thread_Dispatch( void );
  *  Set the Start.stack field to the address of the stack.
  *
  *  @param[in] the_thread is the thread where the stack space is requested
- *  
+ *
  *  @retval actual size allocated after any adjustment
  *  @retval zero if the allocation failed
  */
@@ -570,7 +570,7 @@ size_t _Thread_Stack_Allocate(
 
 /**
  *  @brief Deallocate Thread Stack
- * 
+ *
  *  Deallocate the Thread's stack.
  */
 void _Thread_Stack_Free(
@@ -664,7 +664,7 @@ void _Thread_Close(
  *  This routine removes any set states for @a the_thread.  It performs
  *  any necessary scheduling operations including the selection of
  *  a new heir thread.
- * 
+ *
  *  - INTERRUPT LATENCY:
  *    + ready chain
  *    + select heir
@@ -679,7 +679,7 @@ void _Thread_Ready(
  *  This routine clears the indicated STATES for @a the_thread.  It performs
  *  any necessary scheduling operations including the selection of
  *  a new heir thread.
- * 
+ *
  *  - INTERRUPT LATENCY:
  *    + priority map
  *    + select heir
@@ -734,7 +734,7 @@ void _Thread_Handler( void );
 
 /**
  *  @brief Ended the delay of a Thread
- *  
+ *
  *  This routine is invoked when a thread must be unblocked at the
  *  end of a time based delay (i.e. wake after or wake when).
  *  It is called by the watchdog handler.
@@ -748,7 +748,7 @@ void _Thread_Delay_ended(
 
 /**
  *  @brief Changes the priority of a thread
- *  
+ *
  *  This routine changes the current priority of @a the_thread to
  *  @a new_priority.  It performs any necessary scheduling operations
  *  including the selection of a new heir thread.
@@ -765,7 +765,7 @@ void _Thread_Change_priority (
 
 /**
  *  @brief Set Thread Priority
- *  
+ *
  *  This routine updates the priority related fields in the_thread
  *  control block to indicate the current priority is now new_priority.
  */
@@ -814,7 +814,7 @@ void rtems_iterate_over_all_threads(
 
 /**
  *  @brief Maps THread Id to a TCB Pointer
- *  
+ *
  *  This function maps thread IDs to thread control
  *  blocks.  If ID corresponds to a local thread, then it
  *  returns the_thread control pointer which maps to ID
@@ -823,7 +823,7 @@ void rtems_iterate_over_all_threads(
  *  to OBJECTS_REMOTE, and the_thread is undefined.
  *  Otherwise, location is set to OBJECTS_ERROR and
  *  the_thread is undefined.
- *  
+ *
  *  @param[in] id is the id of the thread.
  *  @param[in] location is the location of the block.
  *
@@ -861,20 +861,18 @@ void _Thread_blocking_operation_Cancel(
   Thread_Control                   *the_thread,
   ISR_Level                         level
 );
-
-
 #if defined(RTEMS_SMP)
 
   /**
    *  @brief _Thread_Dispatch_initialization
-   * 
+   *
    *  This routine initializes the thread dispatching subsystem.
    */
   void _Thread_Dispatch_initialization(void);
 
   /**
    *  @brief _Thread_Dispatch_in_critical_section
-   * 
+   *
    * This routine returns true if thread dispatch indicates
    * that we are in a critical section.
    */
@@ -882,15 +880,15 @@ void _Thread_blocking_operation_Cancel(
 
   /**
    *  @brief _Thread_Dispatch_get_disable_level
-   * 
+   *
    * This routine returns value of the the thread dispatch level.
    */
   uint32_t _Thread_Dispatch_get_disable_level(void);
 
   /**
    *  @brief _Thread_Dispatch_set_disable_level
-   * 
-   * This routine sets thread dispatch level to the 
+   *
+   * This routine sets thread dispatch level to the
    * value passed in.
    */
   uint32_t _Thread_Dispatch_set_disable_level(uint32_t value);
@@ -904,7 +902,7 @@ void _Thread_blocking_operation_Cancel(
 
   /**
    *  @brief _Thread_Dispatch_decrement_disable_level
-   * 
+   *
    * This routine decrements the thread dispatch level.
    */
   uint32_t _Thread_Dispatch_decrement_disable_level(void);
diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h
index ee7801c4e3..a2653b3a02 100644
--- a/cpukit/score/include/rtems/score/threadq.h
+++ b/cpukit/score/include/rtems/score/threadq.h
@@ -88,10 +88,10 @@ Thread_Control *_Thread_queue_Dequeue(
  *
  *  This routine blocks a thread, places it on a thread, and optionally
  *  starts a timeout timer.
- * 
+ *
  *  @param[in] the_thread_queue pointer to threadq
  *  @param[in] timeout interval to wait
- * 
+ *
  *  - INTERRUPT LATENCY:
  *    + single case
  */
@@ -109,7 +109,7 @@ void _Thread_queue_Enqueue_with_handler(
  *  the_thread is removed from the_thread_queue and reinserted using
  *  its new priority.  This method has no impact on the state of the_thread
  *  or of any timeouts associated with this blocking.
- * 
+ *
  *  @param[in] the_thread_queue pointer to a threadq header
  *  @param[in] the_thread pointer to a thread control block
  */
@@ -123,7 +123,7 @@ void _Thread_queue_Requeue(
  *
  *  This routine removes @a the_thread from @a the_thread_queue
  *  and cancels any timeouts associated with this blocking.
- * 
+ *
  *  @param[in] the_thread_queue is the pointer to the ThreadQ header
  *  @param[in] the_thread is the pointer to a thread control block that is to be removed
  */
@@ -176,7 +176,7 @@ void _Thread_queue_Flush(
  *  This routine initializes the_thread_queue based on the
  *  discipline indicated in attribute_set.  The state set on
  *  threads which block on the_thread_queue is state.
- * 
+ *
  *  @param[in] the_thread_queue is the pointer to a threadq header
  *  @param[in] discipline is the queueing discipline
  *  @param[in] state is the state of waiting threads
@@ -199,7 +199,7 @@ void _Thread_queue_Initialize(
  *    + single case
  *
  * @param[in] the_thread_queue is a pointer to a thread queue
- * 
+ *
  * @retval thread dequeued
  * @retval NULL if no thread are waiting on the_thread_queue
  */
@@ -216,7 +216,7 @@ Thread_Control *_Thread_queue_Dequeue_priority(
  *
  *  @param[in] the_thread_queue is the pointer to threadq
  *  @param[in] thread is the thread to insert
- * 
+ *
  *  - INTERRUPT LATENCY:
  *    + forward less than
  *    + forward equal
@@ -234,10 +234,10 @@ Thread_blocking_operation_States _Thread_queue_Enqueue_priority (
  *  and cancels any timeouts associated with this blocking.
  *  @param[in] the_thread_queue pointer to a threadq header
  *  @param[in] the_thread pointer to a thread control block
- *  @param[in] requeuing true if requeuing and should not alter 
+ *  @param[in] requeuing true if requeuing and should not alter
  *         timeout or state
  *  - INTERRUPT LATENCY:
- *    + EXTRACT_PRIORITY 
+ *    + EXTRACT_PRIORITY
  */
 void _Thread_queue_Extract_priority_helper(
   Thread_queue_Control *the_thread_queue,
@@ -253,8 +253,6 @@ void _Thread_queue_Extract_priority_helper(
 
 #define _Thread_queue_Extract_priority( _the_thread_queue, _the_thread ) \
   _Thread_queue_Extract_priority_helper( _the_thread_queue, _the_thread, false )
-
-
 /**
  *  @brief Returns highest priority thread on the_thread_queue
  *
@@ -275,6 +273,14 @@ Thread_Control *_Thread_queue_First_priority(
  *  This function returns a pointer to the thread which has
  *  been waiting the longest on  the_thread_queue.  If no
  *  threads are waiting on the_thread_queue, then NULL is returned.
+ *
+ *  @param[in] the_thread_queue is the pointer to threadq
+ *
+ *  @return thread dequeued or NULL
+ *
+ *  - INTERRUPT LATENCY:
+ *    + check sync
+ *    + FIFO
  */
 Thread_Control *_Thread_queue_Dequeue_fifo(
   Thread_queue_Control *the_thread_queue
@@ -286,11 +292,11 @@ Thread_Control *_Thread_queue_Dequeue_fifo(
  *  This routine enqueues the currently executing thread on
  *  the_thread_queue with an optional timeout using the
  *  FIFO discipline.
- * 
+ *
  *    @param[in] the_thread_queue pointer to threadq
  *    @param[in] the_thread pointer to the thread to block
  *    @param[in] level_p interrupt level in case the operation blocks actually
- * 
+ *
  *  - INTERRUPT LATENCY:
  *    + single case
  */
@@ -317,6 +323,10 @@ void _Thread_queue_Extract_fifo(
  *  This function returns a pointer to the "first" thread
  *  on the_thread_queue.  The first thread is the thread
  *  which has been waiting longest on the_thread_queue.
+ *
+ *  @param[in] the_thread_queue is the pointer to threadq
+ *
+ *  @return first thread or NULL
  */
 Thread_Control *_Thread_queue_First_fifo(
   Thread_queue_Control *the_thread_queue
@@ -330,7 +340,7 @@ Thread_Control *_Thread_queue_First_fifo(
  *  enqueue.  The task represented by ID will be unblocked and
  *  its status code will be set in it's control block to indicate
  *  that a timeout has occurred.
- * 
+ *
  *  @param[in] id thread id
  */
 void _Thread_queue_Timeout (
diff --git a/cpukit/score/include/rtems/score/timespec.h b/cpukit/score/include/rtems/score/timespec.h
index 4e0c6e8e1c..41bb8bb3ef 100644
--- a/cpukit/score/include/rtems/score/timespec.h
+++ b/cpukit/score/include/rtems/score/timespec.h
@@ -149,7 +149,7 @@ bool _Timespec_Less_than(
   )
 
 /**
- * @brief Add to a Timespec
+ *  @brief Add to a Timespec
  *
  *  This routine adds two timespecs.  The second argument is added
  *  to the first.
diff --git a/cpukit/score/include/rtems/score/watchdog.h b/cpukit/score/include/rtems/score/watchdog.h
index a3b033666e..1471f84b28 100644
--- a/cpukit/score/include/rtems/score/watchdog.h
+++ b/cpukit/score/include/rtems/score/watchdog.h
@@ -326,7 +326,7 @@ void _Watchdog_Report_chain(
 );
 
 /**
- * @brief Default nanoseconds since last tick handler.
+ * @brief Default Nanoseconds Since Last Tick Handler
  *
  * @retval 0 Always.
  */