score misc: Score misc: Clean up Doxygen #11 (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/8013204

20 files changed, 119 insertions, 207 deletions

diff --git a/cpukit/score/src/corebarrierwait.c b/cpukit/score/src/corebarrierwait.c
index 0a2a1b7267..e8ab6292ee 100644
--- a/cpukit/score/src/corebarrierwait.c
+++ b/cpukit/score/src/corebarrierwait.c
@@ -1,10 +1,11 @@
-/*
- *  SuperCore Barrier Handler
- *
- *  DESCRIPTION:
- *
- *  This package is part of the implementation of the SuperCore Barrier Handler.
+/**
+ *  @file
  *
+ *  @brief Wait For The Barrier
+ *  @ingroup ScoreBarrier
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2006.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,23 +25,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/threadq.h>
 
-/*
- *  _CORE_barrier_Wait
- *
- *  Input parameters:
- *    the_barrier - pointer to barrier control block
- *    id          - id of object to wait on
- *    wait        - true if wait is allowed, false otherwise
- *    timeout     - number of ticks to wait (0 means forever)
- *    api_barrier_mp_support - api dependent MP support actions
- *
- *  Output parameters:  NONE
- *
- *  INTERRUPT LATENCY:
- *    available
- *    wait
- */
-
 void _CORE_barrier_Wait(
   CORE_barrier_Control                *the_barrier,
   Objects_Id                           id,
diff --git a/cpukit/score/src/coremutex.c b/cpukit/score/src/coremutex.c
index 596fa3f256..951bec63cd 100644
--- a/cpukit/score/src/coremutex.c
+++ b/cpukit/score/src/coremutex.c
@@ -1,11 +1,11 @@
-/*
- *  Mutex Handler
- *
- *  DESCRIPTION:
- *
- *  This package is the implementation of the Mutex Handler.
- *  This handler provides synchronization and mutual exclusion capabilities.
+/**
+ *  @file
  *
+ *  @brief Initialize a Core Mutex
+ *  @ingroup ScoreMutex
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -25,20 +25,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/threadq.h>
 
-/*
- *  _CORE_mutex_Initialize
- *
- *  This routine initializes a mutex at create time and set the control
- *  structure according to the values passed.
- *
- *  Input parameters:
- *    the_mutex             - the mutex control block to initialize
- *    the_mutex_attributes  - the mutex attributes specified at create time
- *    initial_lock          - mutex initial lock or unlocked status
- *
- *  Output parameters:  NONE
- */
-
 CORE_mutex_Status _CORE_mutex_Initialize(
   CORE_mutex_Control           *the_mutex,
   CORE_mutex_Attributes        *the_mutex_attributes,
diff --git a/cpukit/score/src/coremutexflush.c b/cpukit/score/src/coremutexflush.c
index 0c41aea8b8..d05dd54d30 100644
--- a/cpukit/score/src/coremutexflush.c
+++ b/cpukit/score/src/coremutexflush.c
@@ -1,11 +1,11 @@
-/*
- *  Mutex Handler
- *
- *  DESCRIPTION:
- *
- *  This package is the implementation of the Mutex Handler.
- *  This handler provides synchronization and mutual exclusion capabilities.
+/**
+ *  @file
  *
+ *  @brief Flush all waiting threads
+ *  @ingroup ScoreMutex
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -25,19 +25,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/threadq.h>
 
-/*
- *  _CORE_mutex_Flush
- *
- *  This function a flushes the mutex's task wait queue.
- *
- *  Input parameters:
- *    the_mutex              - the mutex to be flushed
- *    remote_extract_callout - function to invoke remotely
- *    status                 - status to pass to thread
- *
- *  Output parameters:  NONE
- */
-
 void _CORE_mutex_Flush(
   CORE_mutex_Control         *the_mutex,
   Thread_queue_Flush_callout  remote_extract_callout,
diff --git a/cpukit/score/src/coremutexseizeintr.c b/cpukit/score/src/coremutexseizeintr.c
index ee4f18f15b..128e8c0de3 100644
--- a/cpukit/score/src/coremutexseizeintr.c
+++ b/cpukit/score/src/coremutexseizeintr.c
@@ -1,6 +1,11 @@
-/*
- *  Mutex Handler -- Seize interrupt disable version
+/**
+ *  @file
  *
+ *  @brief Trylock CORE Mutex Seize Interrupt
+ *  @ingroup ScoreMutex
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/corerwlockobtainread.c b/cpukit/score/src/corerwlockobtainread.c
index a8ea78ba1e..18df39d296 100644
--- a/cpukit/score/src/corerwlockobtainread.c
+++ b/cpukit/score/src/corerwlockobtainread.c
@@ -1,6 +1,11 @@
+/**
+ * @file 
+ * 
+ * @brief Obtain RWLock for reading
+ * @ingroup ScoreRWLock
+ */
+
 /*
- *  SuperCore RWLock Handler -- Obtain RWLock for reading
- *
  *  COPYRIGHT (c) 1989-2006.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,20 +24,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/watchdog.h>
 
-/*
- *  _CORE_rwlock_Obtain_for_reading
- *
- *  This function waits for the rwlock to become available.  Optionally,
- *  a limit may be placed on the duration of the spin.
- *
- *  Input parameters:
- *    the_rwlock    - the rwlock control block to initialize
- *    timeout_allowed - true if timeout allowed
- *    timeout         - the maximum number of ticks to spin
- *
- *  Output parameters:  NONE
- */
-
 void _CORE_RWLock_Obtain_for_reading(
   CORE_RWLock_Control                 *the_rwlock,
   Objects_Id                           id,
diff --git a/cpukit/score/src/corespinlockwait.c b/cpukit/score/src/corespinlockwait.c
index eb1f1388a7..fa2fb11216 100644
--- a/cpukit/score/src/corespinlockwait.c
+++ b/cpukit/score/src/corespinlockwait.c
@@ -1,6 +1,11 @@
 /*
- *  SuperCore Spinlock Handler -- Wait for Spinlock
+ *  @file
  *
+ *  @brief Wait for Spinlock
+ *  @ingroup ScoreSpinlock
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/iterateoverthreads.c b/cpukit/score/src/iterateoverthreads.c
index 4cdb5ea2d9..78e769bb00 100644
--- a/cpukit/score/src/iterateoverthreads.c
+++ b/cpukit/score/src/iterateoverthreads.c
@@ -1,10 +1,11 @@
-/*
- *  rtems_iterate_over_all_threads
- *
- *  This function operates by as follows:
- *    for all threads
- *         invoke specified function
+/**
+ *  @file
  *
+ *  @brief Iterates Over All Threads
+ *  @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/objectget.c b/cpukit/score/src/objectget.c
index f2a549afec..eca8ea9925 100644
--- a/cpukit/score/src/objectget.c
+++ b/cpukit/score/src/objectget.c
@@ -1,7 +1,11 @@
 /*
- *  Object Handler
- *
+ *  @file
  *
+ *  @brief Get Object
+ *  @ingroup Score
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -26,25 +30,6 @@
 #include <rtems/score/sysstate.h>
 #include <rtems/score/isr.h>
 
-/*
- * _Objects_Get
- *
- * This routine sets the object pointer for the given
- * object id based on the given object information structure.
- *
- * Input parameters:
- *   information - pointer to entry in table for this class
- *   id          - object id to search for
- *   location    - address of where to store the location
- *
- * Output parameters:
- *   returns  - address of object if local
- *   location - one of the following:
- *                  OBJECTS_ERROR  - invalid object ID
- *                  OBJECTS_REMOTE - remote object
- *                  OBJECTS_LOCAL  - local object
- */
-
 Objects_Control *_Objects_Get(
   Objects_Information *information,
   Objects_Id           id,
diff --git a/cpukit/score/src/objectidtoname.c b/cpukit/score/src/objectidtoname.c
index 2698c17c25..1c0d926838 100644
--- a/cpukit/score/src/objectidtoname.c
+++ b/cpukit/score/src/objectidtoname.c
@@ -1,7 +1,11 @@
 /*
- *  Obtain Object Name Given ID
- *
+ *  @file
  *
+ *  @brief Object id to name
+ *  @ingroup Score
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2003.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -18,19 +22,6 @@
 #include <rtems/score/object.h>
 #include <rtems/score/thread.h>
 
-/*
- *  _Objects_Id_to_name
- *
- *  DESCRIPTION:
- *
- *  This routine returns the name associated with the given ID.
- *
- *  INPUT:
- *
- *  id   - id of object to lookup name
- *  name - pointer to location in which to store name
- *
- */
 Objects_Name_or_id_lookup_errors _Objects_Id_to_name (
   Objects_Id      id,
   Objects_Name   *name
diff --git a/cpukit/score/src/objectnametoid.c b/cpukit/score/src/objectnametoid.c
index 15700a0aff..7648f22cc4 100644
--- a/cpukit/score/src/objectnametoid.c
+++ b/cpukit/score/src/objectnametoid.c
@@ -1,6 +1,11 @@
-/*
- *  Object Handler
+/**
+ *  @file
  *
+ *  @brief Object Name To Id
+ *  @ingroup Score
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -25,24 +30,6 @@
 #include <rtems/score/sysstate.h>
 #include <rtems/score/isr.h>
 
-/*
- *  _Objects_Name_to_id_u32
- *
- *  These kernel routines search the object table(s) for the given
- *  object name and returns the associated object id.
- *
- *  Input parameters:
- *    information - object information
- *    name        - user defined object name
- *    node        - node indentifier (0 indicates any node)
- *    id          - address of return ID
- *
- *  Output parameters:
- *    id                                   - object id
- *    OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL - if successful
- *    error code                           - if unsuccessful
- */
-
 Objects_Name_or_id_lookup_errors _Objects_Name_to_id_u32(
   Objects_Information *information,
   uint32_t             name,
diff --git a/cpukit/score/src/rbtreeget.c b/cpukit/score/src/rbtreeget.c
index 81e9161a37..1570d472c8 100644
--- a/cpukit/score/src/rbtreeget.c
+++ b/cpukit/score/src/rbtreeget.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Obtain the min or max node of a rbtree
+ *  @ingroup ScoreRBTree
+ */
+
 /*
  *  Copyright (c) 2010 Gedare Bloom.
  *
@@ -15,24 +22,6 @@
 #include <rtems/score/rbtree.h>
 #include <rtems/score/isr.h>
 
-/*
- *  _RBTree_Get
- *
- *  This kernel routine returns a pointer to a node taken from the
- *  given rbtree.
- *
- *  Input parameters:
- *    the_rbtree - pointer to rbtree header
- *    dir - specifies min (0) or max (1)
- *
- *  Output parameters:
- *    return_node - pointer to node in rbtree allocated
- *    NULL   - if no nodes available
- *
- *  INTERRUPT LATENCY:
- *    only case
- */
-
 RBTree_Node *_RBTree_Get(
   RBTree_Control *the_rbtree,
   RBTree_Direction dir
diff --git a/cpukit/score/src/schedulercbsallocate.c b/cpukit/score/src/schedulercbsallocate.c
index 226bc8ac44..cf348ee95e 100644
--- a/cpukit/score/src/schedulercbsallocate.c
+++ b/cpukit/score/src/schedulercbsallocate.c
@@ -1,4 +1,11 @@
 /*
+ *  @file
+ *
+ *  @brief Scheduler CBS Allocate
+ *  @ingroup ScoreScheduler
+ */
+
+/*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/schedulerpriority.c b/cpukit/score/src/schedulerpriority.c
index 127df9e515..e6176e8d05 100644
--- a/cpukit/score/src/schedulerpriority.c
+++ b/cpukit/score/src/schedulerpriority.c
@@ -1,6 +1,11 @@
 /*
- *  Scheduler Handler
+ *  @file
  *
+ *  @brief Initialize Scheduler Priority
+ *  @ingroup ScoreScheduler
+ */
+
+/*
  *  Copyright (C) 2010 Gedare Bloom.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/schedulersimpleunblock.c b/cpukit/score/src/schedulersimpleunblock.c
index 5d8ea2881e..4c482bd752 100644
--- a/cpukit/score/src/schedulersimpleunblock.c
+++ b/cpukit/score/src/schedulersimpleunblock.c
@@ -1,6 +1,11 @@
+/**
+ * @file 
+ * 
+ * @brief Scheduler Simple Handler / Unblock
+ * @ingroup ScoreScheduler
+ */
+
 /*
- *  Scheduler Simple Handler / Unblock
- *
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/threadhandler.c b/cpukit/score/src/threadhandler.c
index 78671422f6..6367c451f4 100644
--- a/cpukit/score/src/threadhandler.c
+++ b/cpukit/score/src/threadhandler.c
@@ -1,7 +1,8 @@
 /**
  *  @file
  *
- *  Initialization Wrapper for all Threads.
+ *  @brief Thread Handler
+ *  @ingroup ScoreThread
  */
 
 /*
@@ -57,29 +58,6 @@
   #define EXECUTE_GLOBAL_CONSTRUCTORS
 #endif
 
-/*
- *  _Thread_Handler
- *
- *  This routine is the "primal" entry point for all threads.
- *  _Context_Initialize() dummies up the thread's initial context
- *  to cause the first Context_Switch() to jump to _Thread_Handler().
- *
- *  This routine is the default thread exitted error handler.  It is
- *  returned to when a thread exits.  The configured fatal error handler
- *  is invoked to process the exit.
- *
- *  NOTE:
- *
- *  On entry, it is assumed all interrupts are blocked and that this
- *  routine needs to set the initial isr level.  This may or may not
- *  actually be needed by the context switch routine and as a result
- *  interrupts may already be at there proper level.  Either way,
- *  setting the initial isr level properly here is safe.
- *
- *  Input parameters:   NONE
- *
- *  Output parameters:  NONE
- */
 void _Thread_Handler( void )
 {
   ISR_Level  level;
diff --git a/cpukit/score/src/threadinitialize.c b/cpukit/score/src/threadinitialize.c
index 7fb650768b..fb22578c3d 100644
--- a/cpukit/score/src/threadinitialize.c
+++ b/cpukit/score/src/threadinitialize.c
@@ -1,6 +1,10 @@
-/*
- *  Thread Handler / Thread Initialize
+/**
+ *  @file
  *
+ *  @brief Initialize Thread
+ *  @ingroup ScoreThread
+ */
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -29,15 +33,6 @@
 #include <rtems/score/watchdog.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  _Thread_Initialize
- *
- *  This routine initializes the specified the thread.  It allocates
- *  all memory associated with this thread.  It completes by adding
- *  the thread to the local object table so operations on this
- *  thread id are allowed.
- */
-
 bool _Thread_Initialize(
   Objects_Information                  *information,
   Thread_Control                       *the_thread,
diff --git a/cpukit/score/src/timespecsubtract.c b/cpukit/score/src/timespecsubtract.c
index f8f356e106..391cbc0a90 100644
--- a/cpukit/score/src/timespecsubtract.c
+++ b/cpukit/score/src/timespecsubtract.c
@@ -1,5 +1,8 @@
 /**
  *  @file  score/src/timespecsubtract.c
+ *
+ *  @brief Subtract Two Timespec
+ *  @ingroup Timespec
  */
 
 /*
diff --git a/cpukit/score/src/ts64divide.c b/cpukit/score/src/ts64divide.c
index 2f8161ae1b..df0b448ecb 100644
--- a/cpukit/score/src/ts64divide.c
+++ b/cpukit/score/src/ts64divide.c
@@ -1,5 +1,8 @@
 /**
- *  @file  score/src/ts64divide.c
+ *  @file
+ *
+ *  @brief Divide Timestamp
+ *  @ingroup SuperCore
  */
 
 /*
diff --git a/cpukit/score/src/ts64equalto.c b/cpukit/score/src/ts64equalto.c
index 8dd226772e..20792208fd 100644
--- a/cpukit/score/src/ts64equalto.c
+++ b/cpukit/score/src/ts64equalto.c
@@ -1,6 +1,9 @@
 /**
- * @file score/src/ts64equalto.c
-*/
+ *  @file
+ *
+ *  @brief Timestamp equal to Operator
+ *  @ingroup SuperCore
+ */
 
 /*
  *  COPYRIGHT (c) 1989-2008.
diff --git a/cpukit/score/src/watchdogadjusttochain.c b/cpukit/score/src/watchdogadjusttochain.c
index f18d78d15c..3b8684a978 100644
--- a/cpukit/score/src/watchdogadjusttochain.c
+++ b/cpukit/score/src/watchdogadjusttochain.c
@@ -1,10 +1,12 @@
 /**
- *  @file watchdogadjusttochain.c
+ *  @file
  *
- *  This is used by the Timer Server task.
+ *  @brief Watchdog Adjust to Chain
+ *  @ingroup ScoreWatchdog
  */
 
-/*  COPYRIGHT (c) 1989-2009.
+/*
+ *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be