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

20 files changed, 129 insertions, 279 deletions

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
 )