Score misc: Clean up Doxygen #8 (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/7970221

20 files changed, 131 insertions, 84 deletions

diff --git a/cpukit/score/src/apimutexallocate.c b/cpukit/score/src/apimutexallocate.c
index 8ba4c9b87e..eb92772332 100644
--- a/cpukit/score/src/apimutexallocate.c
+++ b/cpukit/score/src/apimutexallocate.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Allocates an API Mutex from the Inactive Set
+ * @ingroup ScoreAPIMutex
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/chainappend.c b/cpukit/score/src/chainappend.c
index 302ca34f32..5774118aeb 100644
--- a/cpukit/score/src/chainappend.c
+++ b/cpukit/score/src/chainappend.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Append a Node on the End of a Chain
+ * @ingroup ScoreChain
+*/
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/chainget.c b/cpukit/score/src/chainget.c
index 991a22910b..82a491fac1 100644
--- a/cpukit/score/src/chainget.c
+++ b/cpukit/score/src/chainget.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Get the First Node
+ * @ingroup ScoreChain
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -16,23 +23,6 @@
 #include <rtems/score/chain.h>
 #include <rtems/score/isr.h>
 
-/*
- *  _Chain_Get
- *
- *  This kernel routine returns a pointer to a node taken from the
- *  given chain.
- *
- *  Input parameters:
- *    the_chain - pointer to chain header
- *
- *  Output parameters:
- *    return_node - pointer to node in chain allocated
- *    CHAIN_END   - if no nodes available
- *
- *  INTERRUPT LATENCY:
- *    only case
- */
-
 Chain_Node *_Chain_Get(
   Chain_Control *the_chain
 )
diff --git a/cpukit/score/src/coremutexsurrender.c b/cpukit/score/src/coremutexsurrender.c
index 33cd942bd6..86ac501ca3 100644
--- a/cpukit/score/src/coremutexsurrender.c
+++ b/cpukit/score/src/coremutexsurrender.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 Surrender the Mutex
+ * @ingroup ScoreMutex
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2006.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/objectextendinformation.c b/cpukit/score/src/objectextendinformation.c
index b94b699835..a6a5c253a1 100644
--- a/cpukit/score/src/objectextendinformation.c
+++ b/cpukit/score/src/objectextendinformation.c
@@ -1,7 +1,11 @@
-/*
- *  Object Handler
- *
+/**
+ * @file
  *
+ * @brief Extend Set of Objects
+ * @ingroup ScoreObject
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/objectgetnext.c b/cpukit/score/src/objectgetnext.c
index 26725957d6..16e16cd8d8 100644
--- a/cpukit/score/src/objectgetnext.c
+++ b/cpukit/score/src/objectgetnext.c
@@ -1,7 +1,11 @@
-/*
- *  Object Handler
- *
+/**
+ * @file
  *
+ * @brief Get Pointer to Next Object that is Active
+ * @ingroup ScoreObject
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/objectnametoidstring.c b/cpukit/score/src/objectnametoidstring.c
index fae262a7db..1b88e06fb4 100644
--- a/cpukit/score/src/objectnametoidstring.c
+++ b/cpukit/score/src/objectnametoidstring.c
@@ -1,6 +1,11 @@
-/*
- *  Object Handler - Object ID to Name (String)
+/**
+ * @file
  *
+ * @brief Object ID to Name
+ * @ingroup ScoreObject
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,23 +33,6 @@
 #include <rtems/score/isr.h>
 
 #if defined(RTEMS_SCORE_OBJECT_ENABLE_STRING_NAMES)
-/*
- *  _Objects_Name_to_id_string
- *
- *  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
- *    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_string(
   Objects_Information *information,
   const char          *name,
diff --git a/cpukit/score/src/objectsetname.c b/cpukit/score/src/objectsetname.c
index 625eb496f3..2bc86cf553 100644
--- a/cpukit/score/src/objectsetname.c
+++ b/cpukit/score/src/objectsetname.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Set Objects Name
+ * @ingroup ScoreObject
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
@@ -20,11 +27,6 @@
 #include <inttypes.h>
 #include <string.h>
 
-
-/*
- *  This method sets the name of an object based upon a C string.
- */
-
 bool _Objects_Set_name(
   Objects_Information *information,
   Objects_Control     *the_object,
diff --git a/cpukit/score/src/scheduler.c b/cpukit/score/src/scheduler.c
index 0e0e8cec05..2ee37e7634 100644
--- a/cpukit/score/src/scheduler.c
+++ b/cpukit/score/src/scheduler.c
@@ -1,6 +1,11 @@
-/*
- *  Scheduler Handler / Initialization
+/**
+ * @file
  *
+ * @brief Scheduler Initialize
+ * @ingroup ScoreScheduler
+ */
+
+/*
  *  Copyright (C) 2010 Gedare Bloom.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/scheduleredf.c b/cpukit/score/src/scheduleredf.c
index d04efa56d2..6b1db632b2 100644
--- a/cpukit/score/src/scheduleredf.c
+++ b/cpukit/score/src/scheduleredf.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Scheduler EDF Initialize and Support
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/scheduleredfreleasejob.c b/cpukit/score/src/scheduleredfreleasejob.c
index 913aa57704..83712ce162 100644
--- a/cpukit/score/src/scheduleredfreleasejob.c
+++ b/cpukit/score/src/scheduleredfreleasejob.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Scheduler EDF Release Job
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/scheduleredfunblock.c b/cpukit/score/src/scheduleredfunblock.c
index 4023100aab..31ed6401af 100644
--- a/cpukit/score/src/scheduleredfunblock.c
+++ b/cpukit/score/src/scheduleredfunblock.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Scheduler EDF Unblock
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulersimplereadyqueueenqueue.c b/cpukit/score/src/schedulersimplereadyqueueenqueue.c
index d0f6d473f3..ea3c2c45ec 100644
--- a/cpukit/score/src/schedulersimplereadyqueueenqueue.c
+++ b/cpukit/score/src/schedulersimplereadyqueueenqueue.c
@@ -1,6 +1,11 @@
-/*
- *  Schedule Simple Handler / Ready Queue Enqueue
+/**
+ * @file
  *
+ * @brief Scheduler Simple Priority Enqueue Ready Thread
+ * @ingroup ScoreScheduler
+ */
+
+/*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/schedulersimpleschedule.c b/cpukit/score/src/schedulersimpleschedule.c
index d34bd89a22..e41fa96483 100644
--- a/cpukit/score/src/schedulersimpleschedule.c
+++ b/cpukit/score/src/schedulersimpleschedule.c
@@ -1,6 +1,11 @@
-/*
- *  Scheduler Simple Handler / Schedule
+/**
+ * @file
  *
+ * @brief Simple Schedule Determine Heir
+ * @ingroup ScoreScheduler
+ */
+
+/*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/schedulersimplesmpblock.c b/cpukit/score/src/schedulersimplesmpblock.c
index 5c8233a840..9d6d979684 100644
--- a/cpukit/score/src/schedulersimplesmpblock.c
+++ b/cpukit/score/src/schedulersimplesmpblock.c
@@ -1,6 +1,11 @@
-/*
- *  Scheduler Simple SMP Handler / Block
+/**
+ * @file
  *
+ * @brief Scheduler Simple Block
+ * @ingroup ScoreScheduler
+ */
+
+/*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/schedulersimpleyield.c b/cpukit/score/src/schedulersimpleyield.c
index 84b5f19595..1d5d48c7e5 100644
--- a/cpukit/score/src/schedulersimpleyield.c
+++ b/cpukit/score/src/schedulersimpleyield.c
@@ -1,6 +1,11 @@
-/*
- *  Scheduler Simple Handler / Yield
+/**
+ * @file
  *
+ * @brief Simple Schedule Yield CPU
+ * @ingroup ScoreScheduler
+ */
+
+/*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/threadqflush.c b/cpukit/score/src/threadqflush.c
index cfeb0501eb..8209d5802c 100644
--- a/cpukit/score/src/threadqflush.c
+++ b/cpukit/score/src/threadqflush.c
@@ -1,7 +1,11 @@
-/*
- *  Thread Queue Handler
- *
+/**
+ * @file
  *
+ * @brief Thread Queue Flush
+ * @ingroup ScoreThreadQ
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,19 +27,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/tqdata.h>
 
-/*
- *  _Thread_queue_Flush
- *
- *  This kernel routine flushes the given thread queue.
- *
- *  Input parameters:
- *    the_thread_queue       - pointer to threadq to be flushed
- *    remote_extract_callout - pointer to routine which extracts a remote thread
- *    status                 - status to return to the thread
- *
- *  Output parameters:  NONE
- */
-
 void _Thread_queue_Flush(
   Thread_queue_Control       *the_thread_queue,
 #if defined(RTEMS_MULTIPROCESSING)
diff --git a/cpukit/score/src/ts64lessthan.c b/cpukit/score/src/ts64lessthan.c
index 53b20daae7..a8fb602e7b 100644
--- a/cpukit/score/src/ts64lessthan.c
+++ b/cpukit/score/src/ts64lessthan.c
@@ -1,5 +1,8 @@
 /**
- * @file score/src/ts64lessthan.c
+ * @file
+ *
+ * @brief Timestamp Less Than Operator
+ * @ingroup SuperCore Timestamp64
 */
 
 /*
diff --git a/cpukit/score/src/ts64toticks.c b/cpukit/score/src/ts64toticks.c
index b35a69c60e..f1b97587d2 100644
--- a/cpukit/score/src/ts64toticks.c
+++ b/cpukit/score/src/ts64toticks.c
@@ -1,5 +1,8 @@
 /**
- *  @file  score/src/ts64toticks.c
+ *  @file
+ *
+ *  @brief Convert 64-bit Timestamp to Number of Ticks
+ *  @ingroup SuperCore Timestamp64
  */
 
 /*
diff --git a/cpukit/score/src/watchdogreport.c b/cpukit/score/src/watchdogreport.c
index 5924db784a..e77c22aeb4 100644
--- a/cpukit/score/src/watchdogreport.c
+++ b/cpukit/score/src/watchdogreport.c
@@ -1,10 +1,12 @@
 /**
  *  @file watchdogreport.c
  *
- *  This should only be used for debugging.
+ *  @brief Report Information on a Single Watchdog Instance
+ *  @ingroup ScoreWatchdog
  */
 
-/*  COPYRIGHT (c) 1989-2008.
+/*
+ *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be