score misc: Clean up Doxygen (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/7978208

8 files changed, 66 insertions, 26 deletions

diff --git a/cpukit/score/include/rtems/score/coremsg.h b/cpukit/score/include/rtems/score/coremsg.h
index 4c1d27e890..cb8ce98475 100644
--- a/cpukit/score/include/rtems/score/coremsg.h
+++ b/cpukit/score/include/rtems/score/coremsg.h
@@ -436,6 +436,8 @@ void _CORE_message_queue_Seize(
 );
 
 /**
+ *  @brief Insert a Message into the Message Queue
+ * 
  *  This kernel routine inserts the specified message into the
  *  message queue.  It is assumed that the message has been filled
  *  in before this routine is called.
@@ -444,6 +446,9 @@ void _CORE_message_queue_Seize(
  *  @param[in] the_message is the message to enqueue
  *  @param[in] submit_type determines whether the message is prepended,
  *         appended, or enqueued in priority order.
+ * 
+ *  - INTERRUPT LATENCY:
+ *    + insert
  */
 void _CORE_message_queue_Insert_message(
   CORE_message_queue_Control        *the_message_queue,
diff --git a/cpukit/score/include/rtems/score/corerwlock.h b/cpukit/score/include/rtems/score/corerwlock.h
index 0b0c806498..1bc5301946 100644
--- a/cpukit/score/include/rtems/score/corerwlock.h
+++ b/cpukit/score/include/rtems/score/corerwlock.h
@@ -157,6 +157,8 @@ void _CORE_RWLock_Obtain_for_reading(
 );
 
 /**
+ *  @brief RWLock Obtain for Writing
+ * 
  *  This routine attempts to obtain the RWLock for write exclusive access.
  *
  *  @param[in] the_rwlock is the RWLock to wait for
diff --git a/cpukit/score/include/rtems/score/corespinlock.h b/cpukit/score/include/rtems/score/corespinlock.h
index 48c944fb7b..e0778607e0 100644
--- a/cpukit/score/include/rtems/score/corespinlock.h
+++ b/cpukit/score/include/rtems/score/corespinlock.h
@@ -140,6 +140,8 @@ CORE_spinlock_Status _CORE_spinlock_Wait(
 );
 
 /**
+ * @brief Manually release Spinlock
+ * 
  *  This routine manually releases the spinlock.  All of the threads waiting
  *  for the spinlock will be readied.
  *
diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h
index 6c6166e14e..232414d19c 100644
--- a/cpukit/score/include/rtems/score/object.h
+++ b/cpukit/score/include/rtems/score/object.h
@@ -50,6 +50,12 @@ extern "C" {
  */
 
 /**
+ *  @defgroup ScoreObject Object Handler
+ *
+ *  @ingroup Score
+ */
+
+/**
  *  The following type defines the control block used to manage
  *  object names.
  */
@@ -450,6 +456,8 @@ void _Objects_Shrink_information(
 );
 
 /**
+ *  @brief Initialize object Information
+ * 
  *  This function initializes an object class information record.
  *  SUPPORTS_GLOBAL is true if the object class supports global
  *  objects, and false otherwise.  Maximum indicates the number
diff --git a/cpukit/score/include/rtems/score/rbtree.h b/cpukit/score/include/rtems/score/rbtree.h
index 82bdb6df7f..e601208c58 100644
--- a/cpukit/score/include/rtems/score/rbtree.h
+++ b/cpukit/score/include/rtems/score/rbtree.h
@@ -223,6 +223,15 @@ RBTree_Node *_RBTree_Get(
  *  This function returns a pointer to the node with key equal to a key
  *  of @a the_node if it exists in the Red-Black Tree @a the_rbtree,
  *  and NULL if not.
+ * 
+ *  @param[in] the_rbtree pointer to rbtree control
+ *  @param[in] the_node node with the key to search for
+ *  @return This method returns pointer to control header of rbtree. * 
+ *          If there is no control header available (the node is not part
+ *          of a tree), then NULL is returned. *
+ *
+ *  - INTERRUPT LATENCY:
+ *    + single case  
  */
 RBTree_Node *_RBTree_Find(
   RBTree_Control *the_rbtree,
diff --git a/cpukit/score/include/rtems/score/schedulerpriority.h b/cpukit/score/include/rtems/score/schedulerpriority.h
index aae8012fdd..21239683a9 100644
--- a/cpukit/score/include/rtems/score/schedulerpriority.h
+++ b/cpukit/score/include/rtems/score/schedulerpriority.h
@@ -69,6 +69,8 @@ typedef struct {
 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
@@ -107,6 +109,7 @@ void _Scheduler_priority_Free(
 );
 
 /**
+ *  @brief Update Scheduler priority 
  *  This routine updates @a the_thread->scheduler based on @a the_scheduler
  *  structures and thread state.
  *
diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h
index e5de3e928c..c4e6e2d854 100644
--- a/cpukit/score/include/rtems/score/thread.h
+++ b/cpukit/score/include/rtems/score/thread.h
@@ -592,6 +592,7 @@ bool _Thread_Start(
 );
 
 /**
+ *  @brief Restart Thread
  *  This support routine restarts the specified task in a way that the
  *  next time this thread executes, it will begin execution at its
  *  original starting point.
diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h
index 873a3393f5..db832f4860 100644
--- a/cpukit/score/include/rtems/score/threadq.h
+++ b/cpukit/score/include/rtems/score/threadq.h
@@ -51,9 +51,8 @@ typedef void ( *Thread_queue_Flush_callout )(
              );
 
 /**
- *
- * The following type defines the callout used for timeout processing
- * methods.
+ *  The following type defines the callout used for timeout processing
+ *  methods.
  */
 typedef void ( *Thread_queue_Timeout_callout )(
                  Objects_Id,
@@ -61,7 +60,7 @@ typedef void ( *Thread_queue_Timeout_callout )(
              );
 
 /**
- * @brief  Thread queue Dequeue
+ *  @brief Thread Queue Dequeue
  *
  *  This function returns a pointer to a thread waiting on
  *  the_thread_queue.  The selection of this thread is based on
@@ -73,7 +72,7 @@ Thread_Control *_Thread_queue_Dequeue(
 );
 
 /**
- * @brief  Thread queue Enqueue Wrapper
+ *  @brief Thread Queue Enqueue Wrapper
  *
  *  This routine enqueues the currently executing thread on
  *  the_thread_queue with an optional timeout.
@@ -84,12 +83,17 @@ Thread_Control *_Thread_queue_Dequeue(
     _timeout, \
     _Thread_queue_Timeout )
 
-
 /**
- * @brief  Thread queue Enqueue
+ *  @brief Thread Queue Enqueue
  *
- *  This routine enqueues the currently executing thread on
- *  the_thread_queue with an optional timeout.
+ *  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
  */
 void _Thread_queue_Enqueue_with_handler(
   Thread_queue_Control*        the_thread_queue,
@@ -98,7 +102,7 @@ void _Thread_queue_Enqueue_with_handler(
 );
 
 /**
- *  @brief Thread queue Requeue
+ *  @brief Thread Queue Requeue
  *
  *  This routine is invoked when a thread changes priority and is
  *  blocked on a thread queue.  If the queue is priority ordered,
@@ -112,7 +116,7 @@ void _Thread_queue_Requeue(
 );
 
 /**
- * @brief  Thread queue Extract
+ *  @brief Thread Queue Extract
  *
  *  This routine removes the_thread from the_thread_queue
  *  and cancels any timeouts associated with this blocking.
@@ -123,7 +127,7 @@ void _Thread_queue_Extract(
 );
 
 /**
- * @brief  Thread queue Extract with proxy
+ *  @brief Thread Queue Extract with proxy
  *
  *  This routine extracts the_thread from the_thread_queue
  *  and ensures that if there is a proxy for this task on
@@ -134,7 +138,7 @@ bool _Thread_queue_Extract_with_proxy(
 );
 
 /**
- * @brief  Thread queue First
+ *  @brief Thread Queue First
  *
  *  This function returns a pointer to the "first" thread
  *  on the_thread_queue.  The "first" thread is selected
@@ -145,7 +149,7 @@ Thread_Control *_Thread_queue_First(
 );
 
 /**
- * @brief  Thread queue Flush
+ *  @brief Thread Queue Flush
  *
  *  This routine unblocks all threads blocked on the_thread_queue
  *  and cancels any associated timeouts.
@@ -157,7 +161,7 @@ void _Thread_queue_Flush(
 );
 
 /**
- * @brief  Thread queue Initialize
+ *  @brief Thread Queue Initialize
  *
  *  This routine initializes the_thread_queue based on the
  *  discipline indicated in attribute_set.  The state set on
@@ -171,7 +175,7 @@ void _Thread_queue_Initialize(
 );
 
 /**
- * @brief  Thread queue Dequeue priority
+ *  @brief Thread Queue Dequeue priority
  *
  *  This function returns a pointer to the highest priority
  *  thread waiting on the_thread_queue.  If no threads are waiting
@@ -182,7 +186,7 @@ Thread_Control *_Thread_queue_Dequeue_priority(
 );
 
 /**
- * @brief  Thread queue Enqueue priority
+ *  @brief Thread Queue Enqueue priority
  *
  *  This routine enqueues the currently executing thread on
  *  the_thread_queue with an optional timeout using the
@@ -195,10 +199,16 @@ Thread_blocking_operation_States _Thread_queue_Enqueue_priority (
 );
 
 /**
- * @brief  Thread queue Extract priority Helper
+ *  @brief Thread Queue Extract priority Helper
  *
  *  This routine removes the_thread from the_thread_queue
  *  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 
+ *         timeout or state
+ *  - INTERRUPT LATENCY:
+ *    + EXTRACT_PRIORITY 
  */
 void _Thread_queue_Extract_priority_helper(
   Thread_queue_Control *the_thread_queue,
@@ -207,7 +217,7 @@ void _Thread_queue_Extract_priority_helper(
 );
 
 /**
- * @brief Thread queue Extract priority
+ *  @brief Thread Queue Extract priority
  *
  * This macro wraps the underlying call and hides the requeuing argument.
  */
@@ -217,7 +227,7 @@ void _Thread_queue_Extract_priority_helper(
 
 
 /**
- * @brief  Thread queue First priority
+ *  @brief Thread Queue First priority
  *
  *  This function returns a pointer to the "first" thread
  *  on the_thread_queue.  The "first" thread is the highest
@@ -228,7 +238,7 @@ Thread_Control *_Thread_queue_First_priority(
 );
 
 /**
- * @brief  Thread queue Dequeue FIFO
+ *  @brief Thread Queue Dequeue FIFO
  *
  *  This function returns a pointer to the thread which has
  *  been waiting the longest on  the_thread_queue.  If no
@@ -239,7 +249,7 @@ Thread_Control *_Thread_queue_Dequeue_fifo(
 );
 
 /**
- * @brief  Thread queue Enqueue FIFO
+ *  @brief Thread Queue Enqueue FIFO
  *
  *  This routine enqueues the currently executing thread on
  *  the_thread_queue with an optional timeout using the
@@ -252,7 +262,7 @@ Thread_blocking_operation_States _Thread_queue_Enqueue_fifo (
 );
 
 /**
- * @brief  Thread queue Extract FIFO
+ *  @brief Thread Queue Extract FIFO
  *
  *  This routine removes the_thread from the_thread_queue
  *  and cancels any timeouts associated with this blocking.
@@ -263,7 +273,7 @@ void _Thread_queue_Extract_fifo(
 );
 
 /**
- * @brief  Thread queue First FIFO
+ *  @brief Thread Queue First FIFO
  *
  *  This function returns a pointer to the "first" thread
  *  on the_thread_queue.  The first thread is the thread
@@ -274,7 +284,7 @@ Thread_Control *_Thread_queue_First_fifo(
 );
 
 /**
- * @brief  Thread queue timeout
+ *  @brief Thread Queue timeout
  *
  *  This routine is invoked when a task's request has not
  *  been satisfied after the timeout interval specified to
@@ -288,7 +298,7 @@ void _Thread_queue_Timeout (
 );
 
 /**
- * @brief Process Thread Queue Timeout
+ *  @brief Process Thread Queue Timeout
  *
  * This is a shared helper routine which makes it easier to have multiple
  * object class specific timeout routines.