score misc: Clean up Doxygen #14 (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/8025204

20 files changed, 140 insertions, 265 deletions

diff --git a/cpukit/rtems/src/barrierident.c b/cpukit/rtems/src/barrierident.c
index 993132d647..dc047f1d27 100644
--- a/cpukit/rtems/src/barrierident.c
+++ b/cpukit/rtems/src/barrierident.c
@@ -1,6 +1,11 @@
-/*
- *  Barrier Manager Name to ID
+/**
+ *  @file
  *
+ *  @brief RTEMS Barrier name to Id
+ *  @ingroup ClassicBarrier
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2006.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -20,22 +25,6 @@
 #include <rtems/rtems/options.h>
 #include <rtems/rtems/barrier.h>
 
-/*
- *  rtems_barrier_ident
- *
- *  This directive returns the system ID associated with
- *  the barrier name.
- *
- *  Input parameters:
- *    name - user defined barrier name
- *    id   - pointer to barrier id
- *
- *  Output parameters:
- *    *id              - barrier id
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_barrier_ident(
   rtems_name  name,
   rtems_id   *id
diff --git a/cpukit/rtems/src/barrierwait.c b/cpukit/rtems/src/barrierwait.c
index 523c4dd7f7..05b592e65b 100644
--- a/cpukit/rtems/src/barrierwait.c
+++ b/cpukit/rtems/src/barrierwait.c
@@ -1,6 +1,11 @@
-/*
- *  Barrier Manager -- Wait at a Barrier
+/**
+ *  @file
  *
+ *  @brief RTEMS Barrier Wait
+ *  @ingroup ClassicBarrier
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -20,20 +25,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/threadq.h>
 
-/*
- *  rtems_barrier_wait
- *
- *  This directive allows a thread to wait at a barrier.
- *
- *  Input parameters:
- *    id         - barrier id
- *    timeout    - number of ticks to wait (0 means wait forever)
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code        - if unsuccessful
- */
-
 rtems_status_code rtems_barrier_wait(
   rtems_id        id,
   rtems_interval  timeout
diff --git a/cpukit/rtems/src/clockgetuptimetimeval.c b/cpukit/rtems/src/clockgetuptimetimeval.c
index 8ecd2fbc4d..c173a71b34 100644
--- a/cpukit/rtems/src/clockgetuptimetimeval.c
+++ b/cpukit/rtems/src/clockgetuptimetimeval.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Gets the System Uptime in the Struct Timeval Format
+ *  @ingroup ClassicClock
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/rtems/src/eventdata.c b/cpukit/rtems/src/eventdata.c
index 3faa657c72..df026bd623 100644
--- a/cpukit/rtems/src/eventdata.c
+++ b/cpukit/rtems/src/eventdata.c
@@ -1,6 +1,11 @@
-/*
- *  Event Manager -- Instantiate Data
+/**
+ *  @file
  *
+ *  @brief Instantiate RTEMS Event Data
+ *  @ingroup ClassicEvent
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -13,7 +18,6 @@
 #include "config.h"
 #endif
 
-/* instantiate RTEMS event data */
 #define RTEMS_EVENT_EXTERN
 
 #include <rtems/system.h>
diff --git a/cpukit/rtems/src/eventsend.c b/cpukit/rtems/src/eventsend.c
index 8f0b027ecf..a16382c048 100644
--- a/cpukit/rtems/src/eventsend.c
+++ b/cpukit/rtems/src/eventsend.c
@@ -1,6 +1,11 @@
-/*
- *  Event Manager
+/**
+ *  @file
  *
+ *  @brief Sends an Event Set to the Target Task
+ *  @ingroup ClassicEvent
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/rtems/src/eventsurrender.c b/cpukit/rtems/src/eventsurrender.c
index 07e7b529e3..05b8481a86 100644
--- a/cpukit/rtems/src/eventsurrender.c
+++ b/cpukit/rtems/src/eventsurrender.c
@@ -1,6 +1,11 @@
-/*
- *  Event Manager
+/**
+ *  @file
  *
+ *  @brief Surrender Event
+ *  @ingroup ClassicEvent
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -15,13 +20,6 @@
 
 #include <rtems/rtems/event.h>
 
-/*
- *  INTERRUPT LATENCY:
- *    before flash
- *    after flash
- *    check sync
- */
-
 void _Event_Surrender(
   Thread_Control                   *the_thread,
   rtems_event_set                   event_in,
diff --git a/cpukit/rtems/src/msgdata.c b/cpukit/rtems/src/msgdata.c
index 7616e9a9db..4e6b937e52 100644
--- a/cpukit/rtems/src/msgdata.c
+++ b/cpukit/rtems/src/msgdata.c
@@ -1,6 +1,11 @@
-/*
- *  Barrier Manager -- Instantiate Data
+/**
+ *  @file
  *
+ *  @brief Instantiate the Message Queue Data
+ *  @ingroup ClassicMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -13,7 +18,6 @@
 #include "config.h"
 #endif
 
-/* instantiate message queue data */
 #define RTEMS_MESSAGE_EXTERN
 
 #include <rtems/system.h>
diff --git a/cpukit/rtems/src/msgqdelete.c b/cpukit/rtems/src/msgqdelete.c
index ed3571e0f4..72fd6a077e 100644
--- a/cpukit/rtems/src/msgqdelete.c
+++ b/cpukit/rtems/src/msgqdelete.c
@@ -1,7 +1,11 @@
-/*
- *  Message Queue Manager
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Delete Message Queue
+ *  @ingroup ClassicMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -32,20 +36,6 @@
 #include <rtems/rtems/options.h>
 #include <rtems/rtems/support.h>
 
-/*
- *  rtems_message_queue_delete
- *
- *  This directive allows a thread to delete the message queue specified
- *  by the given queue identifier.
- *
- *  Input parameters:
- *    id - queue id
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code        - if unsuccessful
- */
-
 rtems_status_code rtems_message_queue_delete(
   rtems_id id
 )
diff --git a/cpukit/rtems/src/msgqident.c b/cpukit/rtems/src/msgqident.c
index 6b1c9630d2..ea527e871b 100644
--- a/cpukit/rtems/src/msgqident.c
+++ b/cpukit/rtems/src/msgqident.c
@@ -1,7 +1,11 @@
-/*
- *  Message Queue Manager
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Message Queue Name to Id
+ *  @ingroup ClassicMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -32,23 +36,6 @@
 #include <rtems/rtems/options.h>
 #include <rtems/rtems/support.h>
 
-/*
- *  rtems_message_queue_ident
- *
- *  This directive returns the system ID associated with
- *  the message queue name.
- *
- *  Input parameters:
- *    name - user defined message queue name
- *    node - node(s) to be searched
- *    id   - pointer to message queue id
- *
- *  Output parameters:
- *    *id               - message queue id
- *    RTEMS_SUCCESSFUL - if successful
- *    error code        - if unsuccessful
- */
-
 rtems_status_code rtems_message_queue_ident(
   rtems_name  name,
   uint32_t    node,
diff --git a/cpukit/rtems/src/ratemoncancel.c b/cpukit/rtems/src/ratemoncancel.c
index b0b8c04671..af6a972a8e 100644
--- a/cpukit/rtems/src/ratemoncancel.c
+++ b/cpukit/rtems/src/ratemoncancel.c
@@ -1,6 +1,11 @@
-/*
- *  Rate Monotonic Manager -- Cancel a Period
+/**
+ *  @file
  *
+ *  @brief RTEMS Rate Monotonic Cancel
+ *  @ingroup ClassicRateMon
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,19 +26,6 @@
 #include <rtems/rtems/ratemon.h>
 #include <rtems/score/thread.h>
 
-/*
- *  rtems_rate_monotonic_cancel
- *
- *  This directive allows a thread to cancel a rate monotonic timer.
- *
- *  Input parameters:
- *    id - rate monotonic id
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful and caller is not the owning thread
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_rate_monotonic_cancel(
   rtems_id id
 )
diff --git a/cpukit/rtems/src/ratemongetstatistics.c b/cpukit/rtems/src/ratemongetstatistics.c
index 017a67e19c..801cd9410f 100644
--- a/cpukit/rtems/src/ratemongetstatistics.c
+++ b/cpukit/rtems/src/ratemongetstatistics.c
@@ -1,6 +1,11 @@
-/*
- *  Rate Monotonic Manager -- Get Statistics
+/**
+ *  @file
  *
+ *  @brief RTEMS Rate Monotonic Get Statistics
+ *  @ingroup ClassicRateMon
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,22 +26,6 @@
 #include <rtems/rtems/ratemon.h>
 #include <rtems/score/thread.h>
 
-/*
- *  rtems_rate_monotonic_get_statistics
- *
- *  This directive allows a thread to obtain statistics information on a
- *  period.
- *
- *  Input parameters:
- *    id         - rate monotonic id
- *    statistics - pointer to statistics control block
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- *
- */
-
 rtems_status_code rtems_rate_monotonic_get_statistics(
   rtems_id                                id,
   rtems_rate_monotonic_period_statistics *statistics
diff --git a/cpukit/rtems/src/ratemonperiod.c b/cpukit/rtems/src/ratemonperiod.c
index 14cd2d5a8e..91f457bbb6 100644
--- a/cpukit/rtems/src/ratemonperiod.c
+++ b/cpukit/rtems/src/ratemonperiod.c
@@ -1,6 +1,11 @@
-/*
- *  Rate Monotonic Manager - Period Blocking and Status
+/**
+ *  @file
  *
+ *  @brief Rate Monotonic Support
+ *  @ingroup ClassicRateMon
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -224,21 +229,6 @@ static void _Rate_monotonic_Update_statistics(
   #endif
 }
 
-
-/*
- *  rtems_rate_monotonic_period
- *
- *  This directive allows a thread to manipulate a rate monotonic timer.
- *
- *  Input parameters:
- *    id     - rate monotonic id
- *    length - length of period (in ticks)
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_rate_monotonic_period(
   rtems_id       id,
   rtems_interval length
diff --git a/cpukit/rtems/src/regiongetinfo.c b/cpukit/rtems/src/regiongetinfo.c
index a1d7d60c0c..fef9f500f7 100644
--- a/cpukit/rtems/src/regiongetinfo.c
+++ b/cpukit/rtems/src/regiongetinfo.c
@@ -1,7 +1,11 @@
-/*
- *  Region Manager
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Get Region Information
+ *  @ingroup ClassicRegion
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,21 +28,6 @@
 #include <rtems/score/apimutex.h>
 #include <rtems/score/thread.h>
 
-/*
- *  rtems_region_get_information
- *
- *  This directive will return information about the region specified.
- *
- *  Input parameters:
- *    id         - region id
- *    the_info   - pointer to region information block
- *
- *  Output parameters:
- *    *the_info   - region information block filled in
- *    RTEMS_SUCCESSFUL - if successful
- *    error code - if unsuccessful
- */
-
 rtems_status_code rtems_region_get_information(
   rtems_id                id,
   Heap_Information_block *the_info
diff --git a/cpukit/rtems/src/regionprocessqueue.c b/cpukit/rtems/src/regionprocessqueue.c
index 1cb50adac8..d7fc555049 100644
--- a/cpukit/rtems/src/regionprocessqueue.c
+++ b/cpukit/rtems/src/regionprocessqueue.c
@@ -1,7 +1,11 @@
-/*
- *  Region Manager
- *
+/**
+ *  @file
  *
+ *  @brief Process Region Queue
+ *  @ingroup ClassicRegion
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,20 +28,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/apimutex.h>
 
-/*
- *  _Region_Process_queue
- *
- *  If enough memory is available to satisfy the rtems_region_get_segment of
- *  the first blocked task, then that task and as many subsequent tasks as
- *  possible will be unblocked with their requests satisfied.
- *
- *  Input parameters:
- *    the_region - the region
- *
- *  Output parameters:
- *    none
- */
-
 void _Region_Process_queue(
   Region_Control *the_region
 )
diff --git a/cpukit/rtems/src/rtemsobjectidgetindex.c b/cpukit/rtems/src/rtemsobjectidgetindex.c
index 72e5e75658..281e896007 100644
--- a/cpukit/rtems/src/rtemsobjectidgetindex.c
+++ b/cpukit/rtems/src/rtemsobjectidgetindex.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Object Helper -- Extract Index From Id
+/**
+ *  @file
  *
+ *  @brief Get Index Portion of Object Id
+ *  @ingroup ClassicClassInfo
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/rtems/src/semident.c b/cpukit/rtems/src/semident.c
index 0c43912265..b770d69ef4 100644
--- a/cpukit/rtems/src/semident.c
+++ b/cpukit/rtems/src/semident.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 Semaphore Name to Id
+ *  @ingroup ClassicSem
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -47,23 +38,6 @@
 
 #include <rtems/score/interr.h>
 
-/*
- *  rtems_semaphore_ident
- *
- *  This directive returns the system ID associated with
- *  the semaphore name.
- *
- *  Input parameters:
- *    name - user defined semaphore name
- *    node - node(s) to be searched
- *    id   - pointer to semaphore id
- *
- *  Output parameters:
- *    *id              - semaphore id
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_semaphore_ident(
   rtems_name  name,
   uint32_t    node,
diff --git a/cpukit/rtems/src/signalsend.c b/cpukit/rtems/src/signalsend.c
index 917a548516..5696007696 100644
--- a/cpukit/rtems/src/signalsend.c
+++ b/cpukit/rtems/src/signalsend.c
@@ -1,7 +1,11 @@
-/*
- *  Signal Manager
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Send Signal
+ *  @ingroup ClassicSignal
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,20 +27,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/rtems/tasks.h>
 
-/*
- *  rtems_signal_send
- *
- *  This directive allows a thread to send signals to a thread.
- *
- *  Input parameters:
- *    id         - thread id
- *    signal_set - signal set
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_signal_send(
   rtems_id          id,
   rtems_signal_set  signal_set
diff --git a/cpukit/rtems/src/tasksetpriority.c b/cpukit/rtems/src/tasksetpriority.c
index f51c565893..5eebe686ae 100644
--- a/cpukit/rtems/src/tasksetpriority.c
+++ b/cpukit/rtems/src/tasksetpriority.c
@@ -1,7 +1,11 @@
-/*
- *  RTEMS Task Manager
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Set Task Priority
+ *  @ingroup ClassicTasks
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -29,24 +33,6 @@
 #include <rtems/score/apiext.h>
 #include <rtems/score/sysstate.h>
 
-/*
- *  rtems_task_set_priority
- *
- *  This directive changes the priority of the specified thread.
- *  The specified thread can be any thread in the system including
- *  the requesting thread.
- *
- *  Input parameters:
- *    id           - thread id (0 indicates requesting thread)
- *    new_priority - thread priority (0 indicates current priority)
- *    old_priority - pointer to previous priority
- *
- *  Output parameters:
- *    old_priority      - previous priority
- *    RTEMS_SUCCESSFUL - if successful
- *    error code        - if unsuccessful
- */
-
 rtems_status_code rtems_task_set_priority(
   rtems_id             id,
   rtems_task_priority  new_priority,
diff --git a/cpukit/rtems/src/timerident.c b/cpukit/rtems/src/timerident.c
index 8f9a607130..2687ef7167 100644
--- a/cpukit/rtems/src/timerident.c
+++ b/cpukit/rtems/src/timerident.c
@@ -1,7 +1,11 @@
-/*
- *  Timer Manager - rtems_timer_ident directive
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Timer Name to Id
+ *  @ingroup ClassicTimer
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2002.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,22 +27,6 @@
 #include <rtems/score/tod.h>
 #include <rtems/score/watchdog.h>
 
-/*
- *  rtems_timer_ident
- *
- *  This directive returns the system ID associated with
- *  the timer name.
- *
- *  Input parameters:
- *    name - user defined message queue name
- *    id   - pointer to timer id
- *
- *  Output parameters:
- *    *id              - message queue id
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_timer_ident(
   rtems_name    name,
   rtems_id     *id
diff --git a/cpukit/rtems/src/workspacegreedy.c b/cpukit/rtems/src/workspacegreedy.c
index 03781412b2..8e43370336 100644
--- a/cpukit/rtems/src/workspacegreedy.c
+++ b/cpukit/rtems/src/workspacegreedy.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Greedy Allocate that Empties the Workspace and Free
+ *  @ingroup ClassicRTEMS
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *