score misc: Score misc: Clean up Doxygen #10 (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/7983216

11 files changed, 92 insertions, 48 deletions

diff --git a/cpukit/score/include/rtems/score/apiext.h b/cpukit/score/include/rtems/score/apiext.h
index afd828ca38..82910bfc0d 100644
--- a/cpukit/score/include/rtems/score/apiext.h
+++ b/cpukit/score/include/rtems/score/apiext.h
@@ -92,16 +92,16 @@ typedef struct {
 SCORE_EXTERN Chain_Control _API_extensions_List;
 
 /**
- * @brief Initialize the API Extensions Handler
+ *  @brief Initialize the API Extensions Handler
  *
  *  This routine initializes the API extension handler.
  */
 void _API_extensions_Initialization( void );
 
 /**
- * @brief Add Extension Set to the Active Set
+ *  @brief Add Extension Set to the Active Set
  *
- *  This routine adds an extension to the active set of API extensions.
+ *  This routine adds @a the_extension to the active set of API extensions.
  *
  *  @param[in] the_extension is the extension set to add.
  */
@@ -110,23 +110,23 @@ void _API_extensions_Add(
 );
 
 #if defined(FUNCTIONALITY_NOT_CURRENTLY_USED_BY_ANY_API)
-  /**
-   * @brief Execute all Pre-Driver Extensions
-   *
-   *  This routine executes all of the predriver callouts.
-   */
+/**
+ *  @brief Execute all Pre-Driver Extensions
+ *
+ *  This routine executes all of the predriver callouts.
+ */
   void _API_extensions_Run_predriver( void );
 #endif
 
 /**
- * @brief Execute all Post-Driver Extensions
+ *  @brief Execute all Post-Driver Extensions
  *
  *  This routine executes all of the postdriver callouts.
  */
 void _API_extensions_Run_postdriver( void );
 
 /**
- * @brief Execute all Post Context Switch Extensions
+ *  @brief Execute all Post Context Switch Extensions
  *
  *  This routine executes all of the post context switch callouts.
  */
diff --git a/cpukit/score/include/rtems/score/apimutex.h b/cpukit/score/include/rtems/score/apimutex.h
index 780b16708c..13b0dddd65 100644
--- a/cpukit/score/include/rtems/score/apimutex.h
+++ b/cpukit/score/include/rtems/score/apimutex.h
@@ -57,10 +57,12 @@ typedef struct {
 SCORE_EXTERN Objects_Information _API_Mutex_Information;
 
 /**
- * @brief Performs the initialization necessary for this handler.
+ *  @brief Initialization for the API Mutexe Handler.
  *
- * The value @a maximum_mutexes is the maximum number of API mutexes that may
- * exist at any time.
+ *  The value @a maximum_mutexes is the maximum number of API mutexes that may
+ *  exist at any time.
+ *
+ *  @param[in] Maximum_mutexex is the maximum number of API mutexes.
  */
 void _API_Mutex_Initialization( uint32_t maximum_mutexes );
 
@@ -71,12 +73,18 @@ void _API_Mutex_Initialization( uint32_t maximum_mutexes );
 void _API_Mutex_Allocate( API_Mutex_Control **mutex );
 
 /**
- * @brief Acquires the specified API mutex @a mutex.
+ *  @brief Acquires the specified API mutex.
  */
-void _API_Mutex_Lock( API_Mutex_Control *mutex );
+void _API_Mutex_Lock(
+   API_Mutex_Control *mutex 
+   );
 
 /**
- * @brief Releases the specified API mutex @a mutex.
+ *  @brief Releases the Specified API Mutex
+ *
+ *  Releases the specified @a mutex.
+ *
+ *  @param[in] mutex is the mutex to be removed.
  */
 void _API_Mutex_Unlock( API_Mutex_Control *mutex );
 
diff --git a/cpukit/score/include/rtems/score/coremsg.h b/cpukit/score/include/rtems/score/coremsg.h
index fccebbf57c..0f468c83bf 100644
--- a/cpukit/score/include/rtems/score/coremsg.h
+++ b/cpukit/score/include/rtems/score/coremsg.h
@@ -336,22 +336,27 @@ uint32_t   _CORE_message_queue_Flush(
  *
  *  @param[in] the_message_queue points to the message queue to flush
  *
- *  @return This method returns the number of message pending messages flushed.
+ *  @return This method returns the number of pending messages flushed.
+ *
+ *  - INTERRUPT LATENCY:
+ *    + single case
  */
 uint32_t   _CORE_message_queue_Flush_support(
   CORE_message_queue_Control *the_message_queue
 );
 
 #if defined(FUNCTIONALITY_NOT_CURRENTLY_USED_BY_ANY_API)
-  /**
-   *  @brief Flush Waiting Threads.
-   *
-   *  This function flushes the threads which are blocked on
-   *  @a the_message_queue's pending message queue.  They are
-   *  unblocked whether blocked sending or receiving.
-   *
-   *  @param[in] the_message_queue points to the message queue to flush
-   */
+/**
+ *  @brief Flush Waiting Threads.
+ *
+ *  This function flushes the threads which are blocked on
+ *  @a the_message_queue's pending message queue.  They are
+ *  unblocked whether blocked sending or receiving. It returns 
+ *  the number of messages flushed from the queue.
+ *
+ *  @param[in] the_message_queue points to the message queue to flush
+ *  @return number of messages flushed from the queue
+ */
   void _CORE_message_queue_Flush_waiting_threads(
     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 f0d3477b22..6d97ab1f23 100644
--- a/cpukit/score/include/rtems/score/corerwlock.h
+++ b/cpukit/score/include/rtems/score/corerwlock.h
@@ -182,7 +182,9 @@ void _CORE_RWLock_Obtain_for_writing(
 );
 
 /**
- *  This routine manually releases the RWLock.  All of the threads waiting
+ *  @brief Releases the RWLock
+ *
+ *  This routine manually releases @a the_rwlock.  All of the threads waiting
  *  for the RWLock will be readied.
  *
  *  @param[in] the_rwlock is the RWLock to surrender
diff --git a/cpukit/score/include/rtems/score/coresem.h b/cpukit/score/include/rtems/score/coresem.h
index 243d0093a2..d7a8494c55 100644
--- a/cpukit/score/include/rtems/score/coresem.h
+++ b/cpukit/score/include/rtems/score/coresem.h
@@ -170,6 +170,8 @@ void _CORE_semaphore_Initialize(
 #endif
 
 /**
+ *  @brief Surrenders a Unit to a Semaphore
+ *
  *  This routine frees a unit to the semaphore.  If a task was blocked waiting
  *  for a unit from this semaphore, then that task will be readied and the unit
  *  given to that task.  Otherwise, the unit will be returned to the semaphore.
diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h
index 6d43b39e81..274347bb0b 100644
--- a/cpukit/score/include/rtems/score/object.h
+++ b/cpukit/score/include/rtems/score/object.h
@@ -779,10 +779,12 @@ Objects_Information *_Objects_Get_information(
 );
 
 /**
+ *  @brief Get Information of an Object from an ID
+ *
  *  This function return the information structure given
- *  an id of an object.
+ *  an @a id of an object.
  *
- *  @param[in] id is an object ID
+ *  @param[in] id is the object ID to get the information from
  *
  *  @return This method returns a pointer to the Object Information Table
  *          for the class of objects which corresponds to this object ID.
@@ -831,10 +833,12 @@ bool _Objects_Set_name(
 );
 
 /**
- *  This function removes the_object from the namespace.
+ *  @brief Removes Object from Namespace
  *
- *  @param[in] information points to an Object Information Table
- *  @param[in] the_object is a pointer to an object
+ *  This function removes @a the_object from the namespace.
+ *
+ *  @param[in] information points to an Object Information Table.
+ *  @param[in] the_object is a pointer to an object.
  */
 void _Objects_Namespace_remove(
   Objects_Information  *information,
diff --git a/cpukit/score/include/rtems/score/schedulercbs.h b/cpukit/score/include/rtems/score/schedulercbs.h
index f4494d0360..d0bc5ee109 100644
--- a/cpukit/score/include/rtems/score/schedulercbs.h
+++ b/cpukit/score/include/rtems/score/schedulercbs.h
@@ -131,18 +131,17 @@ typedef struct {
 extern Scheduler_CBS_Server **_Scheduler_CBS_Server_list;
 
 /**
- *  @brief Scheduler CBS Unblock
+ *  @brief Unblocks a Thread from the Queue
  *
  *  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.
+ *  variables, for example the heir thread. It is checked whether the 
+ *  remaining budget is sufficient. If not, the thread continues as a 
+ *  new job in order to protect concurrent threads.
  *
- *  It is checked whether the remaining budget is sufficient. If not, the
- *  thread continues as a new job in order to protect concurrent threads.
+ *  @param[in] the_thread will be unblocked.
  *
  *  @note This has to be asessed as missed deadline of the current job.
- *
- *  @param[in] the_thread will be unblocked.
  */
 void _Scheduler_CBS_Unblock(
   Thread_Control    *the_thread
@@ -301,10 +300,13 @@ int _Scheduler_CBS_Get_server_id (
 );
 
 /**
- *  @brief _Scheduler_CBS_Set_parameters
+ *  @brief Set Parameters for CBS Scheduling
  *
  *  Change CBS scheduling parameters.
  *
+ *  @param[in] server_id is the ID of the server.
+ *  @param[in] parameters are the parameters to set.
+ *
  *  @return status code.
  */
 int _Scheduler_CBS_Set_parameters (
diff --git a/cpukit/score/include/rtems/score/scheduleredf.h b/cpukit/score/include/rtems/score/scheduleredf.h
index 967733f22d..8381184858 100644
--- a/cpukit/score/include/rtems/score/scheduleredf.h
+++ b/cpukit/score/include/rtems/score/scheduleredf.h
@@ -200,7 +200,7 @@ void _Scheduler_EDF_Enqueue(
 );
 
 /**
- *  @brief Scheduler EDF Enqueue first
+ *  @brief Enqueues a thread to the ready queue
  *
  *  This routine puts @a the_thread to the rbtree ready queue.
  *  For the EDF scheduler this is the same as @a _Scheduler_EDF_Enqueue.
diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h
index 502ef8e8ec..845b6e0723 100644
--- a/cpukit/score/include/rtems/score/thread.h
+++ b/cpukit/score/include/rtems/score/thread.h
@@ -603,9 +603,17 @@ bool _Thread_Initialize(
 );
 
 /**
+ *  @brief Initializes Thread and Executes it
+ *
  *  This routine initializes the executable information for a thread
  *  and makes it ready to execute.  After this routine executes, the
  *  thread competes with all other threads for CPU time.
+ *
+ *  @param the_thread is the thread to be initialized
+ *  @param the_prototype 
+ *  @param entry_point
+ *  @param pointer_argument
+ *  @param numeric_argument
  */
 bool _Thread_Start(
   Thread_Control            *the_thread,
@@ -690,9 +698,18 @@ void _Thread_Clear_state(
 );
 
 /**
- *  This routine sets the indicated states for @a the_thread.  It performs
+ *  @brief Sets States for a Thread
+ *
+ *  This routine sets the indicated @a 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 set the state for. 
+ *  @param[in] state is the state to set the_thread to.
+ *
+ *  - INTERRUPT LATENCY:
+ *   + ready chain
+ *   + select map
  */
 void _Thread_Set_state(
   Thread_Control *the_thread,
@@ -716,8 +733,12 @@ void _Thread_Set_transient(
 );
 
 /**
- *  This routine initializes the context of the_thread to its
+ *  @brief Initializes Enviroment for A Thread
+ *
+ *  This routine initializes the context of @a the_thread to its
  *  appropriate starting state.
+ *  
+ *  @param[in] the_thread is the pointer to the thread control block.
  */
 void _Thread_Load_environment(
   Thread_Control *the_thread
diff --git a/cpukit/score/include/rtems/score/timestamp.h b/cpukit/score/include/rtems/score/timestamp.h
index fb16886947..951c37413d 100644
--- a/cpukit/score/include/rtems/score/timestamp.h
+++ b/cpukit/score/include/rtems/score/timestamp.h
@@ -73,9 +73,9 @@ extern "C" {
 #endif
 
 /**
- *  @brief Set Timestamp to Seconds Nanosecond
+ *  @brief Set Timestamp to Specified Seconds and Nanoseconds
  *
- *  This method sets the timestamp to the specified seconds and nanoseconds
+ *  This method sets the timestamp to the specified @a _seconds and @a _nanoseconds
  *  value.
  *
  *  @param[in] _time points to the timestamp instance to validate.
@@ -328,9 +328,9 @@ extern "C" {
 #endif
 
 /**
- *  @brief Convert Timestamp to struct timespec
+ *  @brief Convert Timestamp to Struct Timespec
  *
- *  This method returns the seconds portion of the specified timestamp
+ *  This method returns the seconds portion of the specified @a _timestamp.
  *
  *  @param[in] _timestamp points to the timestamp
  *  @param[in] _timespec points to the timespec
diff --git a/cpukit/score/include/rtems/score/tod.h b/cpukit/score/include/rtems/score/tod.h
index 5d10a509e0..eb743b737a 100644
--- a/cpukit/score/include/rtems/score/tod.h
+++ b/cpukit/score/include/rtems/score/tod.h
@@ -166,9 +166,9 @@ SCORE_EXTERN TOD_Control _TOD;
   _Timestamp_Get_seconds(&_TOD.now)
 
 /**
- *  @brief _TOD_Handler_initialization
+ *  @brief Initializes the Time of Day Handler
  *
- *  This routine performs the initialization necessary for this handler.
+ *  Performs the initialization necessary for the Time Of Day handler.
  */
 void _TOD_Handler_initialization(void);