Score misc: Clean up Doxygen #4 (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/7985215

29 files changed, 229 insertions, 293 deletions

diff --git a/cpukit/score/include/rtems/score/corerwlock.h b/cpukit/score/include/rtems/score/corerwlock.h
index 1bc5301946..f0d3477b22 100644
--- a/cpukit/score/include/rtems/score/corerwlock.h
+++ b/cpukit/score/include/rtems/score/corerwlock.h
@@ -125,6 +125,8 @@ typedef struct {
 }   CORE_RWLock_Control;
 
 /**
+ *  @brief Initialize a RWlock
+ *
  *  This routine initializes the RWLock based on the parameters passed.
  *
  *  @param[in] the_rwlock is the RWLock to initialize
diff --git a/cpukit/score/include/rtems/score/interr.h b/cpukit/score/include/rtems/score/interr.h
index e325e68d3b..6198dbd94a 100644
--- a/cpukit/score/include/rtems/score/interr.h
+++ b/cpukit/score/include/rtems/score/interr.h
@@ -172,6 +172,13 @@ extern Internal_errors_Information _Internal_errors_What_happened;
  * determines that a fatal error has occurred or a final system state is
  * reached (for example after exit()).
  *
+ * This routine will invoke the fatal error handler supplied by the user
+ * followed by the the default one provided by the executive.  The default
+ * error handler assumes no hardware is present to help inform the user
+ * of the problem.  Halt stores the error code in a known register,
+ * disables interrupts, and halts the CPU.  If the CPU does not have a
+ * halt instruction, it will loop to itself.
+ *
  * The first action of this function is to call the fatal handler of the user
  * extensions.  For the initial extensions the following conditions are
  * required
@@ -191,6 +198,12 @@ extern Internal_errors_Information _Internal_errors_What_happened;
  *
  * The final step is to call the CPU specific _CPU_Fatal_halt().
  *
+ * @param[in] the_source is what subsystem the error originated in
+ * @param[in] is_internal is if the error was internally generated
+ * @param[in] the_error is the fatal error status code
+ *
+ * @note The the_error is not necessarily a directive status code.
+ *
  * @see rtems_fatal_error_occurred() and rtems_fatal().
  */
 void _Internal_error_Occurred(
diff --git a/cpukit/score/include/rtems/score/isr.h b/cpukit/score/include/rtems/score/isr.h
index 531b872256..8a0574951b 100644
--- a/cpukit/score/include/rtems/score/isr.h
+++ b/cpukit/score/include/rtems/score/isr.h
@@ -87,7 +87,9 @@ SCORE_EXTERN ISR_Handler_entry *_ISR_Vector_table;
 #endif
 
 /**
- *  This routine performs the initialization necessary for this handler.
+ *  @brief Initialize the ISR handler
+ *
+ *  This routine performs the initialization necessary for the ISR handler.
  */
 void _ISR_Handler_initialization ( void );
 
diff --git a/cpukit/score/include/rtems/score/mpci.h b/cpukit/score/include/rtems/score/mpci.h
index 59e60f10fe..5fce6a274f 100644
--- a/cpukit/score/include/rtems/score/mpci.h
+++ b/cpukit/score/include/rtems/score/mpci.h
@@ -196,6 +196,8 @@ SCORE_EXTERN MPCI_Packet_processor
                _MPCI_Packet_processors[MP_PACKET_CLASSES_LAST+1];
 
 /**
+ *  @brief Initialization of the MPCI Handler  
+ *
  *  This routine performs the initialization necessary for this handler.
  *
  *  @param[in] timeout_status is the value which should be returned to
@@ -206,11 +208,15 @@ void _MPCI_Handler_initialization(
 );
 
 /**
+ *  @brief Create the MPCI Server Thread
+ * 
  *  This routine creates the packet receive server used in MP systems.
  */
 void _MPCI_Create_server( void );
 
 /**
+ *  @brief Initialize the MPCI driver
+ *
  *  This routine initializes the MPCI driver by
  *  invoking the user provided MPCI initialization callout.
  */
@@ -242,6 +248,8 @@ void _MPCI_Register_packet_processor(
 MP_packet_Prefix *_MPCI_Get_packet ( void );
 
 /**
+ *  @brief Deallocate a packet
+ *
  *  This routine deallocates a packet by invoking the user provided
  *  MPCI return packet callout.
  *
@@ -252,6 +260,8 @@ void _MPCI_Return_packet (
 );
 
 /**
+ *  @brief Send a process packet
+ *
  *  This routine sends a process packet by invoking the user provided
  *  MPCI send callout.
  *
@@ -264,6 +274,8 @@ void _MPCI_Send_process_packet (
 );
 
 /**
+ *  @brief Send a request packet
+ *
  *  This routine sends a request packet by invoking the user provided
  *  MPCI send callout.
  *
@@ -283,6 +295,8 @@ uint32_t _MPCI_Send_request_packet (
 );
 
 /**
+ *  @brief Send a response packet
+ *
  *  This routine sends a response packet by invoking the user provided
  *  MPCI send callout.
  *
@@ -295,6 +309,8 @@ void _MPCI_Send_response_packet (
 );
 
 /**
+ *  @brief Receive a packet
+ *
  *  This routine receives a packet by invoking the user provided
  *  MPCI receive callout.
  *
@@ -303,6 +319,8 @@ void _MPCI_Send_response_packet (
 MP_packet_Prefix  *_MPCI_Receive_packet ( void );
 
 /**
+ *  @brief Pass a packet to the thread
+ *
  *  This routine is responsible for passing @a the_packet to the thread
  *  waiting on the remote operation to complete.  The unblocked thread is
  *  responsible for eventually freeing @a the_packet.
@@ -317,6 +335,8 @@ Thread_Control *_MPCI_Process_response (
 );
 
 /**
+ *  @brief Receive and process all packets
+ *
  *  This is the server thread which receives and processes all MCPI packets.
  *
  *  @param[in] ignored is the thread argument.  It is not used.
@@ -326,11 +346,15 @@ Thread _MPCI_Receive_server(
 );
 
 /**
+ *  @brief Announce the availability of a packet
+ *
  *  This routine informs RTEMS of the availability of an MPCI packet.
  */
 void _MPCI_Announce ( void );
 
 /**
+ *  @brief Perform a process on another node
+ *
  *  This routine performs a remote procedure call so that a
  *  process operation can be performed on another node.
  *
@@ -361,6 +385,8 @@ void _MPCI_Internal_packets_Send_process_packet (
  */
 
 /**
+ *  @brief Perform requested action from another node
+ *
  *  This routine performs the actions specific to this package for
  *  the request from another node.
  */
@@ -391,7 +417,9 @@ void _MPCI_Internal_packets_Process_packet (
  */
 
 /**
- *  This routine is used to obtain a internal threads mp packet.
+ *  @brief Obtain an internal thread
+ *
+ *  This routine is used to obtain an internal threads MP packet.
  */
 MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void );
 
diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h
index c9176e7e5b..1dec9930d1 100644
--- a/cpukit/score/include/rtems/score/object.h
+++ b/cpukit/score/include/rtems/score/object.h
@@ -447,8 +447,13 @@ void _Objects_Extend_information(
 );
 
 /**
+ *  @brief Shrink an object class information record
+ * 
  *  This function shrink an object class information record.
- *
+ *  The object's name and object space are released. The local_table
+ *  etc block does not shrink. The InActive list needs to be scanned
+ *  to find the objects are remove them.
+ *  
  *  @param[in] information points to an object class information block.
  */
 void _Objects_Shrink_information(
diff --git a/cpukit/score/include/rtems/score/schedulerpriority.h b/cpukit/score/include/rtems/score/schedulerpriority.h
index 63e36696cd..844d043eb4 100644
--- a/cpukit/score/include/rtems/score/schedulerpriority.h
+++ b/cpukit/score/include/rtems/score/schedulerpriority.h
@@ -83,6 +83,8 @@ void _Scheduler_priority_Block(
 );
 
 /**
+ *  @brief schedule entry point
+ *
  *  This kernel routine sets the heir thread to be the next ready thread
  *  by invoking the_scheduler->ready_queue->operations->first().
  */
diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h
index fd49b8c340..1c8723f70a 100644
--- a/cpukit/score/include/rtems/score/thread.h
+++ b/cpukit/score/include/rtems/score/thread.h
@@ -524,23 +524,36 @@ void _Thread_Create_idle(void);
 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.  As part
- *  of this process, it is responsible for the following actions:
- *
+ *  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();
+ *
+ *  INTERRUPT LATENCY:
+ *    dispatch thread
+ *    no dispatch thread
  */
 void _Thread_Dispatch( void );
 
 /**
+ *  @brief Stack Allocate Helper
+ *
  *  Allocate the requested stack space for the thread.
- *  return the actual size allocated after any adjustment
- *  or return zero if the allocation failed.
- *  Set the Start.stack field to the address of the stack
+ *  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
  */
-
 size_t _Thread_Stack_Allocate(
   Thread_Control *the_thread,
   size_t          stack_size
@@ -606,8 +619,15 @@ bool _Thread_Restart(
 );
 
 /**
+ *  @brief Resets a thread to its initial state
+ *
  *  This routine resets a thread to its initial state but does
- *  not restart it.
+ *  not restart it. Some APIs do this in separate
+ *  operations and this division helps support this.
+ *
+ *  @param[in] the_thread is the thread to resets
+ *  @param[in] pointer_argument
+ *  @param[in] numeric_argument
  */
 void _Thread_Reset(
   Thread_Control            *the_thread,
@@ -688,8 +708,13 @@ void _Thread_Load_environment(
 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.
+ *
+ *  @param[in] id is the thread id
  */
 void _Thread_Delay_ended(
   Objects_Id  id,
diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h
index 1999ea14ff..5a6e710a8b 100644
--- a/cpukit/score/include/rtems/score/threadq.h
+++ b/cpukit/score/include/rtems/score/threadq.h
@@ -180,9 +180,16 @@ void _Thread_queue_Initialize(
 /**
  *  @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
- *  on the_thread_queue, then NULL is returned.
+ *  This routine removes a thread from the specified PRIORITY based
+ *  threadq, unblocks it, and cancels its timeout timer.
+ *
+ *  - INTERRUPT LATENCY:
+ *    + 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
  */
 Thread_Control *_Thread_queue_Dequeue_priority(
   Thread_queue_Control *the_thread_queue
diff --git a/cpukit/score/include/rtems/score/watchdog.h b/cpukit/score/include/rtems/score/watchdog.h
index 01b36b3be7..a3b033666e 100644
--- a/cpukit/score/include/rtems/score/watchdog.h
+++ b/cpukit/score/include/rtems/score/watchdog.h
@@ -263,6 +263,7 @@ void _Watchdog_Adjust_to_chain(
  *
  *  This routine inserts @a the_watchdog into the @a header watchdog chain
  *  for a time of @a units.
+ *  Update the delta interval counters.
  *
  *  @param[in] header is @a the_watchdog list to insert @a the_watchdog on
  *  @param[in] the_watchdog is the watchdog to insert
@@ -277,6 +278,7 @@ void _Watchdog_Insert (
  *
  *  This routine is invoked at appropriate intervals to update
  *  the @a header watchdog chain.
+ *  This routine decrements the delta counter in response to a tick.
  *
  *  @param[in] header is the watchdog chain to tickle
  */
diff --git a/cpukit/score/src/corerwlock.c b/cpukit/score/src/corerwlock.c
index 7feea25f3a..7ed84a5824 100644
--- a/cpukit/score/src/corerwlock.c
+++ b/cpukit/score/src/corerwlock.c
@@ -1,10 +1,11 @@
-/*
- *  SuperCore RWLock Handler
- *
- *  DESCRIPTION:
- *
- *  This package is part of the implementation of the SuperCore RWLock Handler.
+/**
+ * @file
  *
+ * @brief
+ * @ingroup ScoreRWLock
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2006.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,19 +24,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/threadq.h>
 
-/*
- *  _CORE_RWLock_Initialize
- *
- *  This function initialize a rwlock and sets the initial value based
- *  on the given count.
- *
- *  Input parameters:
- *    the_rwlock            - the rwlock control block to initialize
- *    the_rwlock_attributes - the attributes specified at create time
- *
- *  Output parameters:  NONE
- */
-
 void _CORE_RWLock_Initialize(
   CORE_RWLock_Control       *the_rwlock,
   CORE_RWLock_Attributes    *the_rwlock_attributes
diff --git a/cpukit/score/src/heapgreedy.c b/cpukit/score/src/heapgreedy.c
index 4711bd5833..60696f84b4 100644
--- a/cpukit/score/src/heapgreedy.c
+++ b/cpukit/score/src/heapgreedy.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @ingroup ScoreHeap
+ *
+ * @brief Heap Handler API.
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/score/src/interr.c b/cpukit/score/src/interr.c
index 3e5eb79d6c..1b895d6fac 100644
--- a/cpukit/score/src/interr.c
+++ b/cpukit/score/src/interr.c
@@ -1,6 +1,11 @@
-/*
- *  Internal Error Handler
+/**
+ * @file
  *
+ * @brief Initiates system termination
+ * @ingroup ScoreIntErr
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,28 +26,6 @@ System_state_Codes _System_state_Current;
 
 Internal_errors_Information _Internal_errors_What_happened;
 
-/*
- *  _Internal_error_Occurred
- *
- *  This routine will invoke the fatal error handler supplied by the user
- *  followed by the the default one provided by the executive.  The default
- *  error handler assumes no hardware is present to help inform the user
- *  of the problem.  Halt stores the error code in a known register,
- *  disables interrupts, and halts the CPU.  If the CPU does not have a
- *  halt instruction, it will loop to itself.
- *
- *  Input parameters:
- *    the_source  - what subsystem the error originated in
- *    is_internal - if the error was internally generated
- *    the_error   - fatal error status code
- *
- *  Output parameters:
- *    As much information as possible is stored in a CPU dependent fashion.
- *    See the CPU dependent code for more information.
- *
- *  NOTE: The the_error is not necessarily a directive status code.
- */
-
 void _Internal_error_Occurred(
   Internal_errors_Source  the_source,
   bool                    is_internal,
diff --git a/cpukit/score/src/isr.c b/cpukit/score/src/isr.c
index 4407be5dcb..a58b0fa736 100644
--- a/cpukit/score/src/isr.c
+++ b/cpukit/score/src/isr.c
@@ -1,7 +1,8 @@
 /**
  *  @file
  *
- *  ISR Handler Initialization
+ *  @brief Initialize the ISR handler
+ *  @ingroup ScoreISR
  */
 
 /*
@@ -24,15 +25,6 @@
 #include <rtems/score/wkspace.h>
 #include <rtems/config.h>
 
-/*  _ISR_Handler_initialization
- *
- *  This routine initializes the ISR handler.
- *
- *  Input parameters: NONE
- *
- *  Output parameters: NONE
- */
-
 void _ISR_Handler_initialization( void )
 {
   _ISR_Nest_level = 0;
diff --git a/cpukit/score/src/mpci.c b/cpukit/score/src/mpci.c
index c4e8934ab6..98b99c7a7e 100644
--- a/cpukit/score/src/mpci.c
+++ b/cpukit/score/src/mpci.c
@@ -1,7 +1,11 @@
-/*
- *  Multiprocessing Communications Interface (MPCI) Handler
- *
+/**
+ * @file
  *
+ * @brief Multiprocessing Communications Interface (MPCI) Handler
+ * @ingroup ScoreMPCI
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -42,12 +46,6 @@ RTEMS_STATIC_ASSERT(
  */
 CORE_semaphore_Control _MPCI_Semaphore;
 
-/*
- *  _MPCI_Handler_initialization
- *
- *  This subprogram performs the initialization necessary for this handler.
- */
-
 void _MPCI_Handler_initialization(
   uint32_t   timeout_status
 )
@@ -98,12 +96,6 @@ void _MPCI_Handler_initialization(
   );
 }
 
-/*
- *  _MPCI_Create_server
- *
- *  This subprogram creates the MPCI receive server.
- */
-
 void _MPCI_Create_server( void )
 {
   Objects_Name name;
@@ -144,25 +136,11 @@ void _MPCI_Create_server( void )
   );
 }
 
-/*
- *  _MPCI_Initialization
- *
- *  This subprogram initializes the MPCI driver by
- *  invoking the user provided MPCI initialization callout.
- */
-
 void _MPCI_Initialization ( void )
 {
   (*_MPCI_table->initialization)();
 }
 
-/*
- *  _MPCI_Register_packet_processor
- *
- *  This routine registers the MPCI packet processor for the
- *  designated object class.
- */
-
 void _MPCI_Register_packet_processor(
   MP_packet_Classes      the_class,
   MPCI_Packet_processor  the_packet_processor
@@ -172,13 +150,6 @@ void _MPCI_Register_packet_processor(
   _MPCI_Packet_processors[ the_class ] = the_packet_processor;
 }
 
-/*
- *  _MPCI_Get_packet
- *
- *  This subprogram obtains a packet by invoking the user provided
- *  MPCI get packet callout.
- */
-
 MP_packet_Prefix *_MPCI_Get_packet ( void )
 {
   MP_packet_Prefix  *the_packet;
@@ -202,13 +173,6 @@ MP_packet_Prefix *_MPCI_Get_packet ( void )
   return the_packet;
 }
 
-/*
- *  _MPCI_Return_packet
- *
- *  This subprogram returns a packet by invoking the user provided
- *  MPCI return packet callout.
- */
-
 void _MPCI_Return_packet (
   MP_packet_Prefix   *the_packet
 )
@@ -216,13 +180,6 @@ void _MPCI_Return_packet (
   (*_MPCI_table->return_packet)( the_packet );
 }
 
-/*
- *  _MPCI_Send_process_packet
- *
- *  This subprogram sends a process packet by invoking the user provided
- *  MPCI send callout.
- */
-
 void _MPCI_Send_process_packet (
   uint32_t            destination,
   MP_packet_Prefix   *the_packet
@@ -235,13 +192,6 @@ void _MPCI_Send_process_packet (
   (*_MPCI_table->send_packet)( destination, the_packet );
 }
 
-/*
- *  _MPCI_Send_request_packet
- *
- *  This subprogram sends a request packet by invoking the user provided
- *  MPCI send callout.
- */
-
 uint32_t   _MPCI_Send_request_packet (
   uint32_t            destination,
   MP_packet_Prefix   *the_packet,
@@ -280,13 +230,6 @@ uint32_t   _MPCI_Send_request_packet (
   return _Thread_Executing->Wait.return_code;
 }
 
-/*
- *  _MPCI_Send_response_packet
- *
- *  This subprogram sends a response packet by invoking the user provided
- *  MPCI send callout.
- */
-
 void _MPCI_Send_response_packet (
   uint32_t            destination,
   MP_packet_Prefix   *the_packet
@@ -297,13 +240,6 @@ void _MPCI_Send_response_packet (
   (*_MPCI_table->send_packet)( destination, the_packet );
 }
 
-/*
- *  _MPCI_Receive_packet
- *
- *  This subprogram receives a packet by invoking the user provided
- *  MPCI receive callout.
- */
-
 MP_packet_Prefix  *_MPCI_Receive_packet ( void )
 {
   MP_packet_Prefix  *the_packet;
@@ -313,13 +249,6 @@ MP_packet_Prefix  *_MPCI_Receive_packet ( void )
   return the_packet;
 }
 
-/*
- *  _MPCI_Process_response
- *
- *  This subprogram obtains a packet by invoking the user provided
- *  MPCI get packet callout.
- */
-
 Thread_Control *_MPCI_Process_response (
   MP_packet_Prefix  *the_packet
 )
@@ -396,11 +325,6 @@ Thread _MPCI_Receive_server(
   return 0;   /* unreached - only to remove warnings */
 }
 
-/*
- *  _MPCI_Announce
- *
- */
-
 void _MPCI_Announce ( void )
 {
   _Thread_Disable_dispatch();
@@ -408,11 +332,6 @@ void _MPCI_Announce ( void )
   _Thread_Enable_dispatch();
 }
 
-/*
- *  _MPCI_Internal_packets_Send_process_packet
- *
- */
-
 void _MPCI_Internal_packets_Send_process_packet (
    MPCI_Internal_Remote_operations operation
 )
@@ -454,12 +373,6 @@ void _MPCI_Internal_packets_Send_process_packet (
  *
  */
 
-/*
- *
- *  _MPCI_Internal_packets_Process_packet
- *
- */
-
 void _MPCI_Internal_packets_Process_packet (
   MP_packet_Prefix  *the_packet_prefix
 )
@@ -510,11 +423,6 @@ void _MPCI_Internal_packets_Process_packet (
  *
  */
 
-/*
- *  _MPCI_Internal_packets_Get_packet
- *
- */
-
 MPCI_Internal_packet *_MPCI_Internal_packets_Get_packet ( void )
 {
   return ( (MPCI_Internal_packet *) _MPCI_Get_packet() );
diff --git a/cpukit/score/src/objectshrinkinformation.c b/cpukit/score/src/objectshrinkinformation.c
index aae6203fba..de32f24d8d 100644
--- a/cpukit/score/src/objectshrinkinformation.c
+++ b/cpukit/score/src/objectshrinkinformation.c
@@ -1,7 +1,11 @@
-/*
- *  Object Handler
- *
+/**
+ * @file
  *
+ * @brief Shrink an Object Class Information Record
+ * @ingroup ScoreCPU
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -26,20 +30,6 @@
 #include <rtems/score/sysstate.h>
 #include <rtems/score/isr.h>
 
-/*
- *  _Objects_Shrink_information
- *
- *  This routine shrinks object information related data structures.
- *  The object's name and object space are released. The local_table
- *  etc block does not shrink. The InActive list needs to be scanned
- *  to find the objects are remove them.
- *  Input parameters:
- *    information     - object information table
- *    the_block       - the block to remove
- *
- *  Output parameters:  NONE
- */
-
 void _Objects_Shrink_information(
   Objects_Information *information
 )
diff --git a/cpukit/score/src/schedulercbs.c b/cpukit/score/src/schedulercbs.c
index 6da8281d7a..7905387018 100644
--- a/cpukit/score/src/schedulercbs.c
+++ b/cpukit/score/src/schedulercbs.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief CBS Scheduler Budget Handler
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulerpriorityschedule.c b/cpukit/score/src/schedulerpriorityschedule.c
index 96114aace9..3757387d06 100644
--- a/cpukit/score/src/schedulerpriorityschedule.c
+++ b/cpukit/score/src/schedulerpriorityschedule.c
@@ -1,6 +1,11 @@
-/*
- *  Scheduler Handler / Scheduler
+/**
+ * @file
  *
+ * @brief Priority Scheduler Schedule Method
+ * @ingroup ScoreScheduler
+ */
+ 
+/*
  *  Copyright (C) 2010 Gedare Bloom.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/schedulersimplesmpunblock.c b/cpukit/score/src/schedulersimplesmpunblock.c
index 64eb20d58f..ef61d483e8 100644
--- a/cpukit/score/src/schedulersimplesmpunblock.c
+++ b/cpukit/score/src/schedulersimplesmpunblock.c
@@ -1,6 +1,11 @@
-/*
- *  Scheduler Simple SMP Handler / Unblock
+/**
+ * @file
  *
+ * @brief Scheduler Simple SMP Unblock Method
+ * @ingroup ScoreScheduler
+ */
+ 
+/*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/threadblockingoperationcancel.c b/cpukit/score/src/threadblockingoperationcancel.c
index ff3932eeb4..d67f995ab1 100644
--- a/cpukit/score/src/threadblockingoperationcancel.c
+++ b/cpukit/score/src/threadblockingoperationcancel.c
@@ -1,7 +1,11 @@
+/**
+ * @file
+ * 
+ * @brief Cancel a Blocking Operation
+ * @ingroup ScoreThread
+ */
+
 /*
- *  Cancel Thread Blocking Operation
- *
- *
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/threaddelayended.c b/cpukit/score/src/threaddelayended.c
index 307064a631..a050669fa5 100644
--- a/cpukit/score/src/threaddelayended.c
+++ b/cpukit/score/src/threaddelayended.c
@@ -1,7 +1,11 @@
+/**
+ * @file
+ * 
+ * @brief End the Delay of a Thread
+ * @ingroup ScoreThread
+ */
+
 /*
- *  Thread Handler
- *
- *
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -27,18 +31,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  _Thread_Delay_ended
- *
- *  This routine processes a thread whose delay period has ended.
- *  It is called by the watchdog handler.
- *
- *  Input parameters:
- *    id - thread id
- *
- *  Output parameters: NONE
- */
-
 void _Thread_Delay_ended(
   Objects_Id  id,
   void       *ignored __attribute__((unused))
diff --git a/cpukit/score/src/threaddispatch.c b/cpukit/score/src/threaddispatch.c
index f3d67b480e..283d27880d 100644
--- a/cpukit/score/src/threaddispatch.c
+++ b/cpukit/score/src/threaddispatch.c
@@ -1,6 +1,11 @@
+/**
+ * @file
+ * 
+ * @brief Dispatch Thread
+ * @ingroup ScoreThread
+ */
+
 /*
- *  Thread Handler
- *
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -35,20 +40,6 @@
   #include <rtems/score/smp.h>
 #endif
 
-/**
- *  _Thread_Dispatch
- *
- *  This kernel routine determines if a dispatch is needed, and if so
- *  dispatches to the heir thread.  Once the heir is running an attempt
- *  is made to dispatch any ASRs.
- *
- *  ALTERNATE ENTRY POINTS:
- *    void _Thread_Enable_dispatch();
- *
- *  INTERRUPT LATENCY:
- *    dispatch thread
- *    no dispatch thread
- */
 void _Thread_Dispatch( void )
 {
   Thread_Control   *executing;
diff --git a/cpukit/score/src/threadqdequeuepriority.c b/cpukit/score/src/threadqdequeuepriority.c
index 8b199cfb83..e31d082253 100644
--- a/cpukit/score/src/threadqdequeuepriority.c
+++ b/cpukit/score/src/threadqdequeuepriority.c
@@ -1,7 +1,10 @@
-/*
- *  Thread Queue Handler
- *
+/**
+ * @file
  *
+ * @brief  Thread Queue Dequeue Priority
+ * @ingroup ScoreThreadQ
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,22 +26,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/tqdata.h>
 
-/*
- *  _Thread_queue_Dequeue_priority
- *
- *  This routine removes a thread from the specified PRIORITY based
- *  threadq, unblocks it, and cancels its timeout timer.
- *
- *  Input parameters:
- *    the_thread_queue - pointer to thread queue
- *
- *  Output parameters:
- *    returns - thread dequeued or NULL
- *
- *  INTERRUPT LATENCY:
- *    only case
- */
-
 Thread_Control *_Thread_queue_Dequeue_priority(
   Thread_queue_Control *the_thread_queue
 )
diff --git a/cpukit/score/src/threadqprocesstimeout.c b/cpukit/score/src/threadqprocesstimeout.c
index b3d2908a6b..c596b959a4 100644
--- a/cpukit/score/src/threadqprocesstimeout.c
+++ b/cpukit/score/src/threadqprocesstimeout.c
@@ -1,7 +1,11 @@
+/**
+ * @file
+ * 
+ * @brief Thread Queue Handler Process Timeout Handler
+ * @ingroup ScoreThreadQ
+ */
+
 /*
- *  Thread Queue Handler - Process Timeout Handler
- *
- *
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/threadreset.c b/cpukit/score/src/threadreset.c
index 18dcce81fc..92cb636657 100644
--- a/cpukit/score/src/threadreset.c
+++ b/cpukit/score/src/threadreset.c
@@ -1,7 +1,11 @@
+/**
+ * @file
+ * 
+ * @brief Reset a Thread to its Initial State
+ * @ingroup ScoreThread
+ */
+
 /*
- *  Thread Handler
- *
- *
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -27,16 +31,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  _Thread_Reset
- *
- *  DESCRIPTION:
- *
- *  This routine resets a thread to its initial stat but does
- *  not actually restart it.  Some APIs do this in separate
- *  operations and this division helps support this.
- */
-
 void _Thread_Reset(
   Thread_Control            *the_thread,
   void                      *pointer_argument,
diff --git a/cpukit/score/src/threadstackallocate.c b/cpukit/score/src/threadstackallocate.c
index d0a2b65a03..dd2049ba42 100644
--- a/cpukit/score/src/threadstackallocate.c
+++ b/cpukit/score/src/threadstackallocate.c
@@ -1,6 +1,12 @@
+/**
+ * @file
+ * 
+ * @brief Stack Allocate Helper
+ * @ingroup ScoreThread
+ */
+
+
 /*
- *  Thread Handler - Stack Allocate Helper
- *
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -27,15 +33,6 @@
 #include <rtems/score/wkspace.h>
 #include <rtems/config.h>
 
-/*
- *  _Thread_Stack_Allocate
- *
- *  Allocate the requested stack space for the thread.
- *  return the actual size allocated after any adjustment
- *  or return zero if the allocation failed.
- *  Set the Start.stack field to the address of the stack
- */
-
 size_t _Thread_Stack_Allocate(
   Thread_Control *the_thread,
   size_t          stack_size
diff --git a/cpukit/score/src/ts64addto.c b/cpukit/score/src/ts64addto.c
index 7793abf408..a57a9eef61 100644
--- a/cpukit/score/src/ts64addto.c
+++ b/cpukit/score/src/ts64addto.c
@@ -1,6 +1,9 @@
 /**
  * @file score/src/ts64addto.c
-*/
+ *
+ * @brief Add to a Timestamp
+ * @ingroup SuperCore
+ */
 
 /*
  *  COPYRIGHT (c) 1989-2008.
diff --git a/cpukit/score/src/ts64getnanoseconds.c b/cpukit/score/src/ts64getnanoseconds.c
index c21ec637e8..c8e3c1ef3c 100644
--- a/cpukit/score/src/ts64getnanoseconds.c
+++ b/cpukit/score/src/ts64getnanoseconds.c
@@ -1,5 +1,8 @@
 /**
  *  @file  score/src/ts64toticks.c
+ *
+ *  @brief Get Nanoseconds Portion of Timestamp
+ *  @ingroup SuperCore
  */
 
 /*
diff --git a/cpukit/score/src/watchdoginsert.c b/cpukit/score/src/watchdoginsert.c
index 5ed8f12bd4..d73e2f061b 100644
--- a/cpukit/score/src/watchdoginsert.c
+++ b/cpukit/score/src/watchdoginsert.c
@@ -1,7 +1,11 @@
-/*
- *  Watchdog Handler
- *
+/**
+ * @file 
  *
+ * @brief Watchdog Insert
+ * @ingroup ScoreWatchdog
+ */
+ 
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -18,13 +22,6 @@
 #include <rtems/score/isr.h>
 #include <rtems/score/watchdog.h>
 
-/*
- *  _Watchdog_Insert
- *
- *  This routine inserts a watchdog timer on to the appropriate delta
- *  chain while updating the delta interval counters.
- */
-
 void _Watchdog_Insert(
   Chain_Control         *header,
   Watchdog_Control      *the_watchdog
diff --git a/cpukit/score/src/watchdogtickle.c b/cpukit/score/src/watchdogtickle.c
index 14714cafd1..ff779588ef 100644
--- a/cpukit/score/src/watchdogtickle.c
+++ b/cpukit/score/src/watchdogtickle.c
@@ -1,7 +1,11 @@
-/*
- *  Watchdog Handler
- *
+/**
+ * @file
  *
+ * @ingroup ScoreWatchdog
+ * @brief Watchdog Tickle
+ */
+ 
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -18,18 +22,6 @@
 #include <rtems/score/isr.h>
 #include <rtems/score/watchdog.h>
 
-/*
- *  _Watchdog_Tickle
- *
- *  This routine decrements the delta counter in response to a tick.  The
- *  delta chain is updated accordingly.
- *
- *  Input parameters:
- *    header - pointer to the delta chain to be tickled
- *
- *  Output parameters: NONE
- */
-
 void _Watchdog_Tickle(
   Chain_Control *header
 )