score misc: Clean up Doxygen #2 (GCI 2012)

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

http://www.google-melange.com/gci/task/view/google/gci2012/7986213

9 files changed, 51 insertions, 14 deletions

diff --git a/cpukit/score/include/rtems/score/chain.h b/cpukit/score/include/rtems/score/chain.h
index 651ee15291..53976e6d78 100644
--- a/cpukit/score/include/rtems/score/chain.h
+++ b/cpukit/score/include/rtems/score/chain.h
@@ -130,10 +130,12 @@ void _Chain_Initialize(
  *  @brief Extract the specified node from a chain
  *
  *  This routine extracts @a the_node from the chain on which it resides.
- *  It disables interrupts to ensure the atomicity of the
- *  extract operation.
+ *  It disables interrupts to ensure the atomicity of the extract operation.
  *
- *  @arg the_node specifies the node to extract
+ *  @param[in] the_node is the node to be extracted
+ *
+ *  - INTERRUPT LATENCY:
+ *    + single case
  */
 void _Chain_Extract(
   Chain_Node *the_node
@@ -160,9 +162,15 @@ Chain_Node *_Chain_Get(
  *
  *  This routine inserts @a the_node on a chain immediately following
  *  @a after_node.
+ *  
+ *  @param[in] after_node is the pointer to the node in chain to be inserted after
+ *  @param[in] node is the pointer to the node to be inserted
  *
  *  @note It disables interrupts to ensure the atomicity
- *  of the extract operation.
+ *  of the insert operation.
+ *
+ *  - INTERRUPT LATENCY:
+ *    + single case
  */
 void _Chain_Insert(
   Chain_Node *after_node,
diff --git a/cpukit/score/include/rtems/score/corebarrier.h b/cpukit/score/include/rtems/score/corebarrier.h
index d284026157..a29780531e 100644
--- a/cpukit/score/include/rtems/score/corebarrier.h
+++ b/cpukit/score/include/rtems/score/corebarrier.h
@@ -156,6 +156,8 @@ 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/corespinlock.h b/cpukit/score/include/rtems/score/corespinlock.h
index e0778607e0..9a4d7af25d 100644
--- a/cpukit/score/include/rtems/score/corespinlock.h
+++ b/cpukit/score/include/rtems/score/corespinlock.h
@@ -110,9 +110,11 @@ typedef struct {
 }   CORE_spinlock_Control;
 
 /**
+ *  @brief Initialized a spinlock
+ *
  *  This routine initializes the spinlock based on the parameters passed.
  *
- *  @param[in] the_spinlock is the spinlock to initialize
+ *  @param[in] the_spinlock is the spinlock control block to initialize
  *  @param[in] the_spinlock_attributes define the behavior of this instance
  */
 void _CORE_spinlock_Initialize(
diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h
index 232414d19c..e8ee057368 100644
--- a/cpukit/score/include/rtems/score/object.h
+++ b/cpukit/score/include/rtems/score/object.h
@@ -774,6 +774,8 @@ Objects_Information *_Objects_Get_information_id(
 );
 
 /**
+ *  @brief _Objects_Get_name_as_string
+ *  
  *  This method objects the name of an object and returns its name
  *  in the form of a C string.  It attempts to be careful about
  *  overflowing the user's string and about returning unprintable characters.
diff --git a/cpukit/score/include/rtems/score/rbtree.h b/cpukit/score/include/rtems/score/rbtree.h
index e601208c58..5f7a103d5e 100644
--- a/cpukit/score/include/rtems/score/rbtree.h
+++ b/cpukit/score/include/rtems/score/rbtree.h
@@ -239,10 +239,17 @@ RBTree_Node *_RBTree_Find(
 );
 
 /**
- * @brief Find the control structure of the tree containing the given node
+ *  @brief Find the control structure of the tree containing the given node
  *
- *  This function returns a pointer to the control structure of the tree
- *  containing @a the_node, if it exists, and NULL if not.
+ *  This function returns a pointer called @a return_header to the control structure of the tree
+ *  containing @a the_node, if it exists, and @a NULL if not.
+ *
+ *  @param[in] the_node is the pointer to the rbtree node.
+ *  @param[out] return_header is the pointer to control header of rbtree.
+ *  @param[out] NULL is returned if there is no control header available.
+ *  
+ *  -INTERRUPT LATENCY:
+ *    + single case
  */
 RBTree_Control *_RBTree_Find_header(
   RBTree_Node *the_node
diff --git a/cpukit/score/include/rtems/score/schedulercbs.h b/cpukit/score/include/rtems/score/schedulercbs.h
index 6aa986d65c..a70f55b27b 100644
--- a/cpukit/score/include/rtems/score/schedulercbs.h
+++ b/cpukit/score/include/rtems/score/schedulercbs.h
@@ -225,6 +225,8 @@ int _Scheduler_CBS_Create_server (
  *
  *  Detach all tasks from a server and destroy it.
  *
+ *  @param[in] server_id is the ID of the server
+ *
  *  @return status code.
  */
 int _Scheduler_CBS_Destroy_server (
diff --git a/cpukit/score/include/rtems/score/schedulersimple.h b/cpukit/score/include/rtems/score/schedulersimple.h
index fb883bb9c3..6237e5c4a1 100644
--- a/cpukit/score/include/rtems/score/schedulersimple.h
+++ b/cpukit/score/include/rtems/score/schedulersimple.h
@@ -75,6 +75,8 @@ void _Scheduler_simple_Schedule( void );
 void _Scheduler_simple_Yield( void );
 
 /**
+ *  @brief Removes a thread from the queue
+ *
  *  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
diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h
index c4e6e2d854..fdacd41564 100644
--- a/cpukit/score/include/rtems/score/thread.h
+++ b/cpukit/score/include/rtems/score/thread.h
@@ -626,7 +626,7 @@ void _Thread_Close(
 );
 
 /**
- *  This routine removes any set states for the_thread.  It performs
+ *  This routine removes any set states for @a the_thread.  It performs
  *  any necessary scheduling operations including the selection of
  *  a new heir thread.
  */
@@ -635,7 +635,7 @@ void _Thread_Ready(
 );
 
 /**
- *  This routine clears the indicated STATES for the_thread.  It performs
+ *  This routine clears the indicated STATES for @a the_thread.  It performs
  *  any necessary scheduling operations including the selection of
  *  a new heir thread.
  */
@@ -645,7 +645,7 @@ void _Thread_Clear_state(
 );
 
 /**
- *  This routine sets the indicated states for the_thread.  It performs
+ *  This routine sets the indicated states for @a the_thread.  It performs
  *  any necessary scheduling operations including the selection of
  *  a new heir thread.
  */
@@ -655,9 +655,16 @@ void _Thread_Set_state(
 );
 
 /**
- *  This routine sets the TRANSIENT state for the_thread.  It performs
+ *  @brief Sets the Transient state for a Thread
+ *
+ *  This routine sets the Transient state for @a the_thread.  It performs
  *  any necessary scheduling operations including the selection of
  *  a new heir thread.
+ *
+ *  @param[in] the_thread is the thread to preform the action upon.
+ *
+ *  - INTERRUPT LATENCY:
+ *    + single case
  */
 void _Thread_Set_transient(
   Thread_Control *the_thread
@@ -748,14 +755,19 @@ 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
- *  and location is set to OBJECTS_LOCAL.  If the thread ID is
+ *  and @a location is set to OBJECTS_LOCAL.  If the thread ID is
  *  global and resides on a remote node, then location is set
  *  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.
  *
  *  @note  The performance of many RTEMS services depends upon
  *         the quick execution of the "good object" path in this
diff --git a/cpukit/score/include/rtems/score/tod.h b/cpukit/score/include/rtems/score/tod.h
index 1f21fdbeae..1f04801578 100644
--- a/cpukit/score/include/rtems/score/tod.h
+++ b/cpukit/score/include/rtems/score/tod.h
@@ -266,7 +266,7 @@ void _TOD_Tickle_ticks( void );
 #define TOD_MILLISECONDS_TO_MICROSECONDS(_ms) ((uint32_t)(_ms) * 1000L)
 
 /**
- *  @brief TOD_MICROSECONDS_TO_TICKS
+ *  @brief Converts microseconds to ticks
  *
  *  This routine converts an interval expressed in microseconds to ticks.
  *