rtems misc: Clean up Doxygen GCI Task #4

http://www.google-melange.com/gci/task/view/google/gci2012/7950205

20 files changed, 140 insertions, 241 deletions

diff --git a/cpukit/rtems/src/clockget.c b/cpukit/rtems/src/clockget.c
index 476d046fbd..45f4c299e1 100644
--- a/cpukit/rtems/src/clockget.c
+++ b/cpukit/rtems/src/clockget.c
@@ -1,6 +1,11 @@
-/*
- *  Clock Manager
+/**
+ *  @file
  *
+ *  @brief Obtain Current Time of Day
+ *  @ingroup ClassicClock
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,23 +26,6 @@
 #include <rtems/score/tod.h>
 #include <rtems/score/watchdog.h>
 
-/*
- *  rtems_clock_get
- *
- *  This directive returns the current date and time.  If the time has
- *  not been set by a tm_set then an error is returned.
- *
- *  Input parameters:
- *    option      - which value to return
- *    time_buffer - pointer to output buffer (a time and date structure
- *                  or an interval)
- *
- *  Output parameters:
- *    time_buffer      - output filled in
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_clock_get(
   rtems_clock_get_options  option,
   void                    *time_buffer
diff --git a/cpukit/rtems/src/clockgettodtimeval.c b/cpukit/rtems/src/clockgettodtimeval.c
index a3fb49d92e..b2d7c52784 100644
--- a/cpukit/rtems/src/clockgettodtimeval.c
+++ b/cpukit/rtems/src/clockgettodtimeval.c
@@ -1,6 +1,11 @@
-/*
- *  Clock Manager - Get TOD in Time Value Format
+/**
+ *  @file
  *
+ *  @brief Obtain TOD in struct timeval Format
+ *  @ingroup ClassicClock
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/rtems/src/dpmem.c b/cpukit/rtems/src/dpmem.c
index 168082dc6d..88f06caeee 100644
--- a/cpukit/rtems/src/dpmem.c
+++ b/cpukit/rtems/src/dpmem.c
@@ -1,6 +1,11 @@
-/*
- *  Dual Port Memory Manager
+/**
+ *  @file
  *
+ *  @brief Dual Ported Memory Manager Initialization
+ *  @ingroup ClassicDPMEM
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -22,17 +27,6 @@
 #include <rtems/score/object.h>
 #include <rtems/score/thread.h>
 
-/*
- *  _Dual_ported_memory_Manager_initialization
- *
- *  This routine initializes all dual-ported memory manager related
- *  data structures.
- *
- *  Input parameters:   NONE
- *
- *  Output parameters:  NONE
- */
-
 void _Dual_ported_memory_Manager_initialization(void)
 {
   _Objects_Initialize_information(
diff --git a/cpukit/rtems/src/eventtimeout.c b/cpukit/rtems/src/eventtimeout.c
index 6e81a804ff..58dee84b1b 100644
--- a/cpukit/rtems/src/eventtimeout.c
+++ b/cpukit/rtems/src/eventtimeout.c
@@ -1,6 +1,11 @@
-/*
- *  Event Manager
+/**
+ *  @file
  *
+ *  @brief Timeout Event
+ *  @ingroup ClassicEvent
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/rtems/src/msg.c b/cpukit/rtems/src/msg.c
index 009cc28e3b..9ce07ebd22 100644
--- a/cpukit/rtems/src/msg.c
+++ b/cpukit/rtems/src/msg.c
@@ -1,7 +1,11 @@
-/*
- *  Message Queue Manager
- *
+/**
+ *  @file
  *
+ *  @brief Message Queue Manager Initialization
+ *  @ingroup ClassicMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -33,17 +37,6 @@
 #include <rtems/rtems/options.h>
 #include <rtems/rtems/support.h>
 
-/*
- *  _Message_queue_Manager_initialization
- *
- *  This routine initializes all message queue manager related
- *  data structures.
- *
- *  Input parameters:   NONE
- *
- *  Output parameters:  NONE
- */
-
 void _Message_queue_Manager_initialization(void)
 {
   _Objects_Initialize_information(
diff --git a/cpukit/rtems/src/msgqcreate.c b/cpukit/rtems/src/msgqcreate.c
index a5cce2bd1d..e65dcacfe6 100644
--- a/cpukit/rtems/src/msgqcreate.c
+++ b/cpukit/rtems/src/msgqcreate.c
@@ -1,7 +1,11 @@
-/*
- *  Message Queue Manager
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Create Message Queue
+ *  @ingroup ClassicMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -32,25 +36,6 @@
 #include <rtems/rtems/options.h>
 #include <rtems/rtems/support.h>
 
-/*
- *  rtems_message_queue_create
- *
- *  This directive creates a message queue by allocating and initializing
- *  a message queue data structure.
- *
- *  Input parameters:
- *    name             - user defined queue name
- *    count            - maximum message and reserved buffer count
- *    max_message_size - maximum size of each message
- *    attribute_set    - process method
- *    id               - pointer to queue
- *
- *  Output parameters:
- *    id                - queue id
- *    RTEMS_SUCCESSFUL  - if successful
- *    error code        - if unsuccessful
- */
-
 rtems_status_code rtems_message_queue_create(
   rtems_name       name,
   uint32_t         count,
diff --git a/cpukit/rtems/src/msgqtranslatereturncode.c b/cpukit/rtems/src/msgqtranslatereturncode.c
index aa3ba0ce74..d7d1a5610d 100644
--- a/cpukit/rtems/src/msgqtranslatereturncode.c
+++ b/cpukit/rtems/src/msgqtranslatereturncode.c
@@ -1,7 +1,11 @@
-/*
- *  Message Queue Manager
- *
+/**
+ *  @file
  *
+ *  @brief Message queue Translate Core Message Queue Return Code
+ *  @ingroup ClassicMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -32,17 +36,6 @@
 #include <rtems/rtems/options.h>
 #include <rtems/rtems/support.h>
 
-/*
- *  _Message_queue_Translate_core_message_queue_return_code
- *
- *  Input parameters:
- *    the_message_queue_status - message_queue status code to translate
- *
- *  Output parameters:
- *    rtems status code - translated RTEMS status code
- *
- */
-
 rtems_status_code _Message_queue_Translate_core_return_code_[] = {
   RTEMS_SUCCESSFUL,         /* CORE_MESSAGE_QUEUE_STATUS_SUCCESSFUL */
   RTEMS_INVALID_SIZE,       /* CORE_MESSAGE_QUEUE_STATUS_INVALID_SIZE */
diff --git a/cpukit/rtems/src/regiongetsegment.c b/cpukit/rtems/src/regiongetsegment.c
index 81d363a065..1f38e5cbce 100644
--- a/cpukit/rtems/src/regiongetsegment.c
+++ b/cpukit/rtems/src/regiongetsegment.c
@@ -1,7 +1,11 @@
-/*
- *  Region Manager
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Get Region Segment
+ *  @ingroup ClassicRegion
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,24 +28,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/apimutex.h>
 
-/*
- *  rtems_region_get_segment
- *
- *  This directive will obtain a segment from the given region.
- *
- *  Input parameters:
- *    id         - region id
- *    size       - segment size in bytes
- *    option_set - wait option
- *    timeout    - number of ticks to wait (0 means wait forever)
- *    segment    - pointer to segment address
- *
- *  Output parameters:
- *    segment    - pointer to segment address filled in
- *    RTEMS_SUCCESSFUL - if successful
- *    error code - if unsuccessful
- */
-
 rtems_status_code rtems_region_get_segment(
   rtems_id           id,
   uintptr_t          size,
diff --git a/cpukit/rtems/src/rtemsbuildname.c b/cpukit/rtems/src/rtemsbuildname.c
index a37db76a78..472a71bdcc 100644
--- a/cpukit/rtems/src/rtemsbuildname.c
+++ b/cpukit/rtems/src/rtemsbuildname.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Object Helper -- Build an Object Name
+/**
+ *  @file
  *
+ *  @brief Build Thirty-Two Bit Object Name
+ *  @ingroup ClassicClassInfo
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/rtems/src/rtemsobjectgetapiclassname.c b/cpukit/rtems/src/rtemsobjectgetapiclassname.c
index 2550006ee8..93495829f8 100644
--- a/cpukit/rtems/src/rtemsobjectgetapiclassname.c
+++ b/cpukit/rtems/src/rtemsobjectgetapiclassname.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Object Helper -- Obtain Name of API
+/**
+ *  @file
  *
+ *  @brief Get Class Name
+ *  @ingroup ClassicClassInfo
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/rtems/src/rtemsobjectgetclassinfo.c b/cpukit/rtems/src/rtemsobjectgetclassinfo.c
index aceab69a43..c801c66669 100644
--- a/cpukit/rtems/src/rtemsobjectgetclassinfo.c
+++ b/cpukit/rtems/src/rtemsobjectgetclassinfo.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Object Helper -- Get Information on Class
+/**
+ *  @file
  *
+ *  @brief Get Class Information
+ *  @ingroup ClassicClassInfo
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/rtems/src/rtemsobjectidapiminimum.c b/cpukit/rtems/src/rtemsobjectidapiminimum.c
index 0c85a14fb2..c6eb871d47 100644
--- a/cpukit/rtems/src/rtemsobjectidapiminimum.c
+++ b/cpukit/rtems/src/rtemsobjectidapiminimum.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Object Helper -- Get Least Valid API Number
+/**
+ *  @file
  *
+ *  @brief Get Lowest Valid API Index
+ *  @ingroup ClassicClassInfo
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/rtems/src/rtemsobjectidgetclass.c b/cpukit/rtems/src/rtemsobjectidgetclass.c
index 2a1a47f948..a9b7df76a7 100644
--- a/cpukit/rtems/src/rtemsobjectidgetclass.c
+++ b/cpukit/rtems/src/rtemsobjectidgetclass.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Object Helper -- Extract Class From Id
+/**
+ *  @file
  *
+ *  @brief Get Class Portion of Object Id
+ *  @ingroup ClassicClassInfo
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/rtems/src/rtemstimerdata.c b/cpukit/rtems/src/rtemstimerdata.c
index 6a735619dd..b3ed7e97bb 100644
--- a/cpukit/rtems/src/rtemstimerdata.c
+++ b/cpukit/rtems/src/rtemstimerdata.c
@@ -1,6 +1,11 @@
-/*
- *  Timer Manager -- Instantiate Data
+/**
+ *  @file
  *
+ *  @brief Instantiate RTEMS Timer Data
+ *  @ingroup ClassicTimer
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -13,7 +18,6 @@
 #include "config.h"
 #endif
 
-/* instantiate RTEMS timer data */
 #define RTEMS_TIMER_EXTERN
 
 #include <rtems/system.h>
diff --git a/cpukit/rtems/src/sem.c b/cpukit/rtems/src/sem.c
index 76c753e114..4e22dacb36 100644
--- a/cpukit/rtems/src/sem.c
+++ b/cpukit/rtems/src/sem.c
@@ -1,20 +1,11 @@
-/*
- *  Semaphore Manager
- *
- *  DESCRIPTION:
- *
- *  This package is the implementation of the Semaphore Manager.
- *  This manager utilizes standard Dijkstra counting semaphores to provide
- *  synchronization and mutual exclusion capabilities.
- *
- *  Directives provided are:
- *
- *     + create a semaphore
- *     + get an ID of a semaphore
- *     + delete a semaphore
- *     + acquire a semaphore
- *     + release a semaphore
+/**
+ *  @file
  *
+ *  @brief Semaphore Manager Initialization
+ *  @ingroup ClassicSem
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -48,16 +39,6 @@
 
 #include <rtems/score/interr.h>
 
-/*
- *  _Semaphore_Manager_initialization
- *
- *  This routine initializes all semaphore manager related data structures.
- *
- *  Input parameters:   NONE
- *
- *  Output parameters:  NONE
- */
-
 void _Semaphore_Manager_initialization(void)
 {
   _Objects_Initialize_information(
diff --git a/cpukit/rtems/src/semdelete.c b/cpukit/rtems/src/semdelete.c
index 54625fac37..57e00db0e5 100644
--- a/cpukit/rtems/src/semdelete.c
+++ b/cpukit/rtems/src/semdelete.c
@@ -1,20 +1,11 @@
-/*
- *  Semaphore Manager
- *
- *  DESCRIPTION:
- *
- *  This package is the implementation of the Semaphore Manager.
- *  This manager utilizes standard Dijkstra counting semaphores to provide
- *  synchronization and mutual exclusion capabilities.
- *
- *  Directives provided are:
- *
- *     + create a semaphore
- *     + get an ID of a semaphore
- *     + delete a semaphore
- *     + acquire a semaphore
- *     + release a semaphore
+/**
+ *  @file
  *
+ *  @brief RTEMS Delete Semaphore
+ *  @ingroup ClassicSem
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -47,21 +38,6 @@
 
 #include <rtems/score/interr.h>
 
-/*
- *  rtems_semaphore_delete
- *
- *  This directive allows a thread to delete a semaphore specified by
- *  the semaphore id.  The semaphore is freed back to the inactive
- *  semaphore chain.
- *
- *  Input parameters:
- *    id - semaphore id
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 #if defined(RTEMS_MULTIPROCESSING)
 #define SEMAPHORE_MP_OBJECT_WAS_DELETED _Semaphore_MP_Send_object_was_deleted
 #else
diff --git a/cpukit/rtems/src/signalmp.c b/cpukit/rtems/src/signalmp.c
index b07f160f98..f70a452208 100644
--- a/cpukit/rtems/src/signalmp.c
+++ b/cpukit/rtems/src/signalmp.c
@@ -1,7 +1,11 @@
-/*
- *  Multiprocessing Support for the Signal Manager
- *
+/**
+ *  @file
  *
+ *  @brief Signal MP Support
+ *  @ingroup ClassicSignalMP
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -39,11 +43,6 @@ RTEMS_STATIC_ASSERT(
  *
  */
 
-/*
- *  _Signal_MP_Send_request_packet
- *
- */
-
 rtems_status_code _Signal_MP_Send_request_packet (
   Signal_MP_Remote_operations operation,
   Objects_Id                  task_id,
@@ -82,11 +81,6 @@ rtems_status_code _Signal_MP_Send_request_packet (
   return RTEMS_INTERNAL_ERROR;
 }
 
-/*
- *  _Signal_MP_Send_response_packet
- *
- */
-
 void _Signal_MP_Send_response_packet (
   Signal_MP_Remote_operations  operation,
   Thread_Control              *the_thread
@@ -119,12 +113,6 @@ void _Signal_MP_Send_response_packet (
   }
 }
 
-/*
- *
- *  _Signal_MP_Process_packet
- *
- */
-
 void _Signal_MP_Process_packet (
   rtems_packet_prefix  *the_packet_prefix
 )
@@ -175,11 +163,6 @@ void _Signal_MP_Process_packet (
  *
  */
 
-/*
- *  _Signal_MP_Get_packet
- *
- */
-
 Signal_MP_Packet *_Signal_MP_Get_packet ( void )
 {
   return ( (Signal_MP_Packet *) _MPCI_Get_packet() );
diff --git a/cpukit/rtems/src/status.c b/cpukit/rtems/src/status.c
index 27d60b5ce7..f89a5e700a 100644
--- a/cpukit/rtems/src/status.c
+++ b/cpukit/rtems/src/status.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Status Object Name Errors to Status Array
+ *  @ingroup ClassicStatus
+ */
+
 /*  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -8,11 +15,6 @@
 
 #include <rtems/rtems/status.h>
 
-/**
- *  This array is used to map SuperCore Object Handler return
- *  codes to Classic API status codes.
- */
-
 const rtems_status_code _Status_Object_name_errors_to_status[] = {
   /** This maps OBJECTS_SUCCESSFUL to RTEMS_SUCCESSFUL. */
   RTEMS_SUCCESSFUL,
diff --git a/cpukit/rtems/src/taskresume.c b/cpukit/rtems/src/taskresume.c
index e53b5426ac..a3a8f73571 100644
--- a/cpukit/rtems/src/taskresume.c
+++ b/cpukit/rtems/src/taskresume.c
@@ -1,7 +1,11 @@
-/*
- *  RTEMS Task Manager
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Resume Task
+ *  @ingroup ClassicTasks
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -29,20 +33,6 @@
 #include <rtems/score/apiext.h>
 #include <rtems/score/sysstate.h>
 
-/*
- *  rtems_task_resume
- *
- *  This directive will remove the specified thread
- *  from the suspended state.
- *
- *  Input parameters:
- *    id - thread id
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_task_resume(
   rtems_id id
 )
diff --git a/cpukit/rtems/src/tasksetnote.c b/cpukit/rtems/src/tasksetnote.c
index 453a2a2f72..b08198db4b 100644
--- a/cpukit/rtems/src/tasksetnote.c
+++ b/cpukit/rtems/src/tasksetnote.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Task Manager
+/**
+ *  @file
  *
+ *  @brief RTEMS Set Task Note
+ *  @ingroup ClassicTasks
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -29,22 +34,6 @@
 #include <rtems/score/apiext.h>
 #include <rtems/score/sysstate.h>
 
-/*
- * rtems_task_set_note
- *
- *  This directive sets the specified notepad contents to the given
- *  note.
- *
- *  Input parameters:
- *    id      - thread id
- *    notepad - notepad number
- *    note    - note value
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_task_set_note(
   rtems_id id,
   uint32_t notepad,