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

9 files changed, 57 insertions, 25 deletions

diff --git a/cpukit/score/include/rtems/score/schedulercbs.h b/cpukit/score/include/rtems/score/schedulercbs.h
index 1751ad13f9..f4494d0360 100644
--- a/cpukit/score/include/rtems/score/schedulercbs.h
+++ b/cpukit/score/include/rtems/score/schedulercbs.h
@@ -259,9 +259,13 @@ int _Scheduler_CBS_Get_remaining_budget (
 );
 
 /**
- *  @brief _Scheduler_CBS_Get_execution_time
+ *  @brief Get relative time info
  *
- *  Retrieve time info relative to the current server.
+ *  Retrieve time info relative to @a server_id. The server status code is returned.
+ *
+ *  @param[in] server_id is the server to get the status code from.
+ *  @param[in] exec_time is the execution time.
+ *  @param[in] abs_time is not apparently used. 
  *
  *  @return status code.
  */
diff --git a/cpukit/score/include/rtems/score/scheduleredf.h b/cpukit/score/include/rtems/score/scheduleredf.h
index 5d7551d422..967733f22d 100644
--- a/cpukit/score/include/rtems/score/scheduleredf.h
+++ b/cpukit/score/include/rtems/score/scheduleredf.h
@@ -105,7 +105,7 @@ extern RBTree_Control _Scheduler_EDF_Ready_queue;
 void _Scheduler_EDF_Initialize( void );
 
 /**
- *  @brief Scheduler EDF Block
+ *  @brief Removes Thread from Ready Queue
  *
  *  This routine removes @a the_thread from the scheduling decision,
  *  that is, removes it from the ready queue.  It performs
@@ -139,7 +139,7 @@ void *_Scheduler_EDF_Allocate(
 );
 
 /**
- *  @brief Scheduler EDF Free
+ *  @brief Frees EDF information of a thread 
  *
  *  This routine frees the EDF specific information of @a the_thread.
  *
diff --git a/cpukit/score/include/rtems/score/schedulerpriority.h b/cpukit/score/include/rtems/score/schedulerpriority.h
index 0e4d52eec5..e04d29823f 100644
--- a/cpukit/score/include/rtems/score/schedulerpriority.h
+++ b/cpukit/score/include/rtems/score/schedulerpriority.h
@@ -175,6 +175,8 @@ void _Scheduler_priority_Enqueue_first(
 );
 
 /**
+ *  @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/schedulersimple.h b/cpukit/score/include/rtems/score/schedulersimple.h
index 97b571d6a6..d04dc6c6ff 100644
--- a/cpukit/score/include/rtems/score/schedulersimple.h
+++ b/cpukit/score/include/rtems/score/schedulersimple.h
@@ -50,7 +50,9 @@ extern "C" {
   }
 
 /**
- * This routine initializes the simple scheduler.
+ *  @brief Initializes simple scheduler
+ *
+ *  This routine initializes the simple scheduler.
  */
 void _Scheduler_simple_Initialize( void );
 
@@ -100,6 +102,8 @@ void _Scheduler_simple_Unblock(
 );
 
 /**
+ *  @brief Removes a thread from a simple queue
+ *
  *  This routine removes a specific thread from the specified
  *  simple-based ready queue.
  *
@@ -110,9 +114,11 @@ void _Scheduler_simple_Extract(
 );
 
 /**
+ *  @brief Puts thread onto the ready queue
+ *
  *  This routine puts @a the_thread on to the ready queue.
  *
- *  @param[in] the_thread is the thread to be blocked
+ *  @param[in] the_thread is the thread to be enqueued
  */
 void _Scheduler_simple_Enqueue(
   Thread_Control *the_thread
@@ -131,6 +137,8 @@ void _Scheduler_simple_Enqueue_first(
 );
 
 /**
+ *  @brief Returns empty placeholder for scheduler
+ *
  *  This routine is a place holder for any memeory allocation needed
  *  by the scheduler.  For the simple scheduler the routine is an empty
  *  place holder.
@@ -146,9 +154,10 @@ void *_Scheduler_simple_Allocate(
 );
 
 /**
- * This routine does nothing, and is used as a stub for Schedule update
+ *  @breif Stub for schedule update
  *
- * The overhead of a function call will still be imposed.
+ *  This routine does nothing, and is used as a stub for Schedule update
+ *  The overhead of a function call will still be imposed.
  *
  *  @param[in] the_thread is the thread to be blocked
  */
@@ -157,9 +166,10 @@ void _Scheduler_simple_Update(
 );
 
 /**
- * This routine does nothing, and is used as a stub for Schedule free
+ *  @brief Stub for schedule free 
  *
- * The overhead of a function call will still be imposed.
+ *  This routine does nothing, and is used as a stub for Schedule free
+ *  The overhead of a function call will still be imposed.
  *
  *  @param[in] the_thread is the thread to be blocked
  */
diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h
index 966867a1d3..9f2060bfca 100644
--- a/cpukit/score/include/rtems/score/thread.h
+++ b/cpukit/score/include/rtems/score/thread.h
@@ -546,9 +546,9 @@ void _Thread_Start_multitasking( void );
  *  ALTERNATE ENTRY POINTS:
  *    void _Thread_Enable_dispatch();
  *
- *  INTERRUPT LATENCY:
- *    dispatch thread
- *    no dispatch thread
+ *  - INTERRUPT LATENCY:
+ *    + dispatch thread
+ *    + no dispatch thread
  */
 void _Thread_Dispatch( void );
 
@@ -739,9 +739,15 @@ void _Thread_Delay_ended(
 );
 
 /**
- *  This routine changes the current priority of the_thread to
- *  new_priority.  It performs any necessary scheduling operations
+ *  @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.
+ *
+ *  @param[in] the_thread is the thread to change
+ *  @param[in] new_priority is the priority to set @a the_thread to
+ *  @param[in] prepend_it is a switch to prepend the thread
  */
 void _Thread_Change_priority (
   Thread_Control   *the_thread,
diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h
index 5a6e710a8b..79de255c72 100644
--- a/cpukit/score/include/rtems/score/threadq.h
+++ b/cpukit/score/include/rtems/score/threadq.h
@@ -119,10 +119,13 @@ void _Thread_queue_Requeue(
 );
 
 /**
- *  @brief Thread Queue Extract
+ *  @brief Extracts Thread from Thread Queue
  *
- *  This routine removes the_thread from the_thread_queue
+ *  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
  */
 void _Thread_queue_Extract(
   Thread_queue_Control *the_thread_queue,
@@ -237,11 +240,14 @@ void _Thread_queue_Extract_priority_helper(
 
 
 /**
- *  @brief Thread Queue First priority
+ *  @brief Returns highest priority thread on the_thread_queue
  *
  *  This function returns a pointer to the "first" thread
- *  on the_thread_queue.  The "first" thread is the highest
- *  priority thread waiting on the_thread_queue.
+ *  on @a the_thread_queue.  The "first" thread is the highest
+ *  priority thread waiting on @a the_thread_queue.
+ *
+ *  @param[in] the_thread_queue is the pointer to the thread queue
+ *  @return first thread or NULL
  */
 Thread_Control *_Thread_queue_First_priority(
   Thread_queue_Control *the_thread_queue
diff --git a/cpukit/score/include/rtems/score/tod.h b/cpukit/score/include/rtems/score/tod.h
index 1f04801578..5d10a509e0 100644
--- a/cpukit/score/include/rtems/score/tod.h
+++ b/cpukit/score/include/rtems/score/tod.h
@@ -173,10 +173,12 @@ SCORE_EXTERN TOD_Control _TOD;
 void _TOD_Handler_initialization(void);
 
 /**
- *  @brief Sets the time of day according to @a tod_as_timestamp.
+ *  @brief Sets the time of day from timestamp
  *
  *  The @a tod_as_timestamp timestamp represents the time since UNIX epoch.
  *  The watchdog seconds chain will be adjusted.
+ *
+ *  @param[in] tod_as_timestamp is the constant of the time of day as a timestamp
  */
 void _TOD_Set_with_timestamp(
   const Timestamp_Control *tod_as_timestamp
@@ -251,6 +253,8 @@ void _TOD_Get_uptime_as_timespec(
 );
 
 /**
+ *  @brief Increments time of day at each clock tick
+ *
  *  This routine increments the ticks field of the current time of
  *  day at each clock tick.
  */
diff --git a/cpukit/score/include/rtems/score/userextimpl.h b/cpukit/score/include/rtems/score/userextimpl.h
index c7d35a8ac9..7a89d9af0c 100644
--- a/cpukit/score/include/rtems/score/userextimpl.h
+++ b/cpukit/score/include/rtems/score/userextimpl.h
@@ -143,7 +143,7 @@ void _User_extensions_Fatal_visitor(
  * @brief Iterates through all user extensions and calls the visitor for each.
  *
  * @param[in, out] arg The argument passed to the visitor.
- * @param[in] visitor The visitor for each extension.
+ * @param[in] visitor is the visitor for each extension.
  */
 void _User_extensions_Iterate(
   void                    *arg,
diff --git a/cpukit/score/include/rtems/score/wkspace.h b/cpukit/score/include/rtems/score/wkspace.h
index db6eb38f96..ffac4cbff0 100644
--- a/cpukit/score/include/rtems/score/wkspace.h
+++ b/cpukit/score/include/rtems/score/wkspace.h
@@ -102,10 +102,10 @@ void *_Workspace_Allocate_or_fatal_error(
 );
 
 /**
- * @brief Duplicates the @a string with memory from the Workspace.
+ * @brief Duplicates String with Memory from the Workspace
  *
- * @param[in] string Pointer to zero terminated string.
- * @param[in] len Length of the string (equal to strlen(string)).
+ * @param[in] string is the pointer to a zero terminated string.
+ * @param[in] len is the length of the string (equal to strlen(string)).
  *
  * @return NULL Not enough memory.
  * @return other Duplicated string.