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

24 files changed, 156 insertions, 95 deletions

diff --git a/cpukit/score/include/rtems/score/chain.h b/cpukit/score/include/rtems/score/chain.h
index 53976e6d78..ebb0f24e8c 100644
--- a/cpukit/score/include/rtems/score/chain.h
+++ b/cpukit/score/include/rtems/score/chain.h
@@ -162,8 +162,9 @@ Chain_Node *_Chain_Get(
  *
  *  This routine inserts @a the_node on a chain immediately following
  *  @a after_node.
- *  
- *  @param[in] after_node is the pointer to the node in chain to be inserted after
+ *
+ *  @param[in] after_node is the pointer to the node in chain to be
+ *             inserted after
  *  @param[in] node is the pointer to the node to be inserted
  *
  *  @note It disables interrupts to ensure the atomicity
@@ -244,6 +245,9 @@ bool _Chain_Prepend_with_empty_check(
  *
  * @retval true The chain is empty now.
  * @retval false The chain contains at least one node now.
+ *
+ *  - INTERRUPT LATENCY:
+ *    + single case
  */
 bool _Chain_Get_with_empty_check(
   Chain_Control *the_chain,
diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h
index 178458681e..29c98a8183 100644
--- a/cpukit/score/include/rtems/score/object.h
+++ b/cpukit/score/include/rtems/score/object.h
@@ -448,12 +448,12 @@ void _Objects_Extend_information(
 
 /**
  *  @brief Shrink an object class information record
- * 
+ *
  *  This function shrink an object class information record.
  *  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.
- *  
+ *
  *  @param[in] information points to an object class information block.
  */
 void _Objects_Shrink_information(
@@ -462,7 +462,7 @@ void _Objects_Shrink_information(
 
 /**
  *  @brief Initialize object Information
- * 
+ *
  *  This function initializes an object class information record.
  *  SUPPORTS_GLOBAL is true if the object class supports global
  *  objects, and false otherwise.  Maximum indicates the number
@@ -516,6 +516,8 @@ unsigned int _Objects_API_maximum_class(
  *  This function allocates a object control block from
  *  the inactive chain of free object control blocks.
  *
+ *  @brief Allocate Object
+ *
  *  @param[in] information points to an object class information block.
  */
 Objects_Control *_Objects_Allocate(
@@ -604,6 +606,8 @@ Objects_Name_or_id_lookup_errors _Objects_Name_to_id_u32(
 
 #if defined(RTEMS_SCORE_OBJECT_ENABLE_STRING_NAMES)
 /**
+ *  @brief Object ID to Name
+ *
  *  This method converts an object name to an Id.  It performs a look up
  *  using the object information block for this object class.
  *
@@ -675,7 +679,7 @@ Objects_Control *_Objects_Get (
 
 /**
  *  @brief Object Get Isr Disable
- *  
+ *
  *  This function maps object ids to object control blocks.
  *  If id corresponds to a local object, then it returns
  *  the_object control pointer which maps to id and location
@@ -709,7 +713,7 @@ Objects_Control *_Objects_Get_isr_disable(
 
 /**
  *  @brief  Get No protection Object
- * 
+ *
  *  This function maps object ids to object control blocks.
  *  If id corresponds to a local object, then it returns
  *  the_object control pointer which maps to id and location
@@ -759,7 +763,7 @@ Objects_Control *_Objects_Get_next(
 
 /**
  *  @brief Get Object Information
- * 
+ *
  *  This function return the information structure given
  *  an the API and Class.  This can be done independent of
  *  the existence of any objects created by the API.
@@ -790,7 +794,7 @@ Objects_Information *_Objects_Get_information_id(
 
 /**
  *  @brief _Objects_Get_name_as_string
- *  
+ *
  *  This method objects the name of an object and returns its name
  *  in the form of a C string.  It attempts to be careful about
  *  overflowing the user's string and about returning unprintable characters.
@@ -809,6 +813,8 @@ char *_Objects_Get_name_as_string(
 );
 
 /**
+ *  @brief Set Objects Name
+ *
  *  This method sets the object name to either a copy of a string
  *  or up to the first four characters of the string based upon
  *  whether this object class uses strings for names.
diff --git a/cpukit/score/include/rtems/score/scheduler.h b/cpukit/score/include/rtems/score/scheduler.h
index dbda8b2d67..117f86a37a 100644
--- a/cpukit/score/include/rtems/score/scheduler.h
+++ b/cpukit/score/include/rtems/score/scheduler.h
@@ -129,6 +129,8 @@ extern Scheduler_Control  _Scheduler;
   (_Scheduler_Priority_compare(_p1,_p2) > 0)
 
 /**
+ *  @brief Scheduler is priority higher than
+ *
  *  This routine initializes the scheduler to the policy chosen by the user
  *  through confdefs, or to the priority scheduler with ready chains by
  *  default.
diff --git a/cpukit/score/include/rtems/score/schedulersimple.h b/cpukit/score/include/rtems/score/schedulersimple.h
index c15114c6c8..6716383205 100644
--- a/cpukit/score/include/rtems/score/schedulersimple.h
+++ b/cpukit/score/include/rtems/score/schedulersimple.h
@@ -64,6 +64,8 @@ void _Scheduler_simple_Initialize( void );
 void _Scheduler_simple_Schedule( void );
 
 /**
+ *  @brief Simple Schedule
+ *
  *  This routine is invoked when a thread wishes to voluntarily
  *  transfer control of the processor to another thread in the queue.
  *  It will remove the running THREAD from the scheduler.informaiton
@@ -126,7 +128,7 @@ void _Scheduler_simple_Enqueue(
 
 /**
  *  @brief Scheduler simple Enqueue first
- *  
+ *
  *  This routine puts @a the_thread to the head of the ready queue.
  *  The thread will be the first thread at its priority level.
  *
@@ -166,7 +168,7 @@ void _Scheduler_simple_Update(
 );
 
 /**
- *  @brief Stub for schedule free 
+ *  @brief Stub for schedule free
  *
  *  This routine does nothing, and is used as a stub for Schedule free
  *  The overhead of a function call will still be imposed.
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