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

9 files changed, 100 insertions, 14 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
  */