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

20 files changed, 148 insertions, 144 deletions

diff --git a/cpukit/score/src/apiext.c b/cpukit/score/src/apiext.c
index b2ca87cba2..73dffee856 100644
--- a/cpukit/score/src/apiext.c
+++ b/cpukit/score/src/apiext.c
@@ -1,7 +1,12 @@
-/*  apiext.c
+/**
+ * @file
  *
- *  XXX
+ * @brief Holding for API Extension Functions
  *
+ * @ingroup ScoreAPIExtension
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -17,19 +22,11 @@
 #include <rtems/system.h>
 #include <rtems/score/apiext.h>
 
-/*
- *  _API_extensions_Initialization
- */
-
 void _API_extensions_Initialization( void )
 {
  _Chain_Initialize_empty( &_API_extensions_List );
 }
 
-/*
- *  _API_extensions_Add
- */
-
 void _API_extensions_Add(
   API_extensions_Control *the_extension
 )
@@ -38,9 +35,6 @@ void _API_extensions_Add(
 }
 
 #if defined(FUNCTIONALITY_NOT_CURRENTLY_USED_BY_ANY_API)
-  /*
-   *  _API_extensions_Run_predriver
-   */
 
   void _API_extensions_Run_predriver( void )
   {
@@ -59,10 +53,6 @@ void _API_extensions_Add(
   }
 #endif
 
-/*
- *  _API_extensions_Run_postdriver
- */
-
 void _API_extensions_Run_postdriver( void )
 {
   Chain_Node             *the_node;
@@ -83,5 +73,3 @@ void _API_extensions_Run_postdriver( void )
       (*the_extension->postdriver_hook)();
   }
 }
-
-/* end of file */
diff --git a/cpukit/score/src/apimutex.c b/cpukit/score/src/apimutex.c
index 0329441411..bc72c91e7c 100644
--- a/cpukit/score/src/apimutex.c
+++ b/cpukit/score/src/apimutex.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ * 
+ * @brief Initialization for the API Mutexe Handler.
+ *
+ * @ingroup ScoreAPIMutex
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/apimutexlock.c b/cpukit/score/src/apimutexlock.c
index aa78279153..174c85826d 100644
--- a/cpukit/score/src/apimutexlock.c
+++ b/cpukit/score/src/apimutexlock.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Acquires the specified API mutex.
+ *
+ * @ingroup ScoreAPIMutex
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/apimutexunlock.c b/cpukit/score/src/apimutexunlock.c
index e8ec597772..6eb54fcbbe 100644
--- a/cpukit/score/src/apimutexunlock.c
+++ b/cpukit/score/src/apimutexunlock.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Releases the Specified API Mutex
+ *
+ * @ingroup ScoreAPIMutex
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/coremsgflushsupp.c b/cpukit/score/src/coremsgflushsupp.c
index 77f56d6fe7..4ea071f74d 100644
--- a/cpukit/score/src/coremsgflushsupp.c
+++ b/cpukit/score/src/coremsgflushsupp.c
@@ -1,12 +1,12 @@
-/*
- *  CORE Message Queue Handler
- *
- *  DESCRIPTION:
+/**
+ * @file
  *
- *  This package is the implementation of the CORE Message Queue Handler.
- *  This core object provides task synchronization and communication functions
- *  via messages passed to queue objects.
+ * @brief Flush Messages Support Routine
  *
+ * @ingroup ScoreMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,23 +28,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  _CORE_message_queue_Flush_support
- *
- *  This message handler routine removes all messages from a message queue
- *  and returns them to the inactive message pool.  The number of messages
- *  flushed from the queue is returned
- *
- *  Input parameters:
- *    the_message_queue - pointer to message queue
- *
- *  Output parameters:
- *    returns - number of messages placed on inactive chain
- *
- *  INTERRUPT LATENCY:
- *    only case
- */
-
 uint32_t   _CORE_message_queue_Flush_support(
   CORE_message_queue_Control *the_message_queue
 )
diff --git a/cpukit/score/src/coremsgflushwait.c b/cpukit/score/src/coremsgflushwait.c
index 58de174cea..f2b1f088b8 100644
--- a/cpukit/score/src/coremsgflushwait.c
+++ b/cpukit/score/src/coremsgflushwait.c
@@ -1,12 +1,12 @@
-/*
- *  CORE Message Queue Handler
- *
- *  DESCRIPTION:
+/**
+ * @file
  *
- *  This package is the implementation of the CORE Message Queue Handler.
- *  This core object provides task synchronization and communication functions
- *  via messages passed to queue objects.
+ * @brief Flush Waiting Threads.
  *
+ * @ingroup ScoreMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -29,18 +29,6 @@
 #include <rtems/score/wkspace.h>
 
 #if defined(FUNCTIONALITY_NOT_CURRENTLY_USED_BY_ANY_API)
-  /*
-   *  _CORE_message_queue_Flush_waiting_threads
-   *
-   *  This function flushes the message_queue's task wait queue.  The number
-   *  of messages flushed from the queue is returned.
-   *
-   *  Input parameters:
-   *    the_message_queue - the message_queue to be flushed
-   *
-   *  Output parameters:
-   *    returns - the number of messages flushed from the queue
-   */
 
   void _CORE_message_queue_Flush_waiting_threads(
     CORE_message_queue_Control *the_message_queue
diff --git a/cpukit/score/src/corerwlockrelease.c b/cpukit/score/src/corerwlockrelease.c
index b13d5f720c..bcae4cb502 100644
--- a/cpukit/score/src/corerwlockrelease.c
+++ b/cpukit/score/src/corerwlockrelease.c
@@ -1,6 +1,12 @@
-/*
- *  SuperCore RWLock Handler -- Release a RWLock
+/**
+ * @file
+ *
+ * @brief Releases the RWLock
  *
+ * @ingroup ScoreRWLock
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2006.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,17 +25,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/watchdog.h>
 
-/*
- *  _CORE_RWLock_Release
- *
- *  This function releases the rwlock.
- *
- *  Input parameters:
- *    the_rwlock    - the rwlock control block to initialize
- *
- *  Output parameters:  NONE
- */
-
 CORE_RWLock_Status _CORE_RWLock_Release(
   CORE_RWLock_Control  *the_rwlock
 )
diff --git a/cpukit/score/src/coresemsurrender.c b/cpukit/score/src/coresemsurrender.c
index 69e71687e2..3d306f82a8 100644
--- a/cpukit/score/src/coresemsurrender.c
+++ b/cpukit/score/src/coresemsurrender.c
@@ -1,12 +1,12 @@
-/*
- *  CORE Semaphore Handler
- *
- *  DESCRIPTION:
+/**
+ * @file
  *
- *  This package is the implementation of the CORE Semaphore Handler.
- *  This core object utilizes standard Dijkstra counting semaphores to provide
- *  synchronization and mutual exclusion capabilities.
+ * @brief Surrenders a Unit to a Semaphore
  *
+ * @ingroup ScoreSemaphore
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -26,21 +26,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/threadq.h>
 
-/*
- *  _CORE_semaphore_Surrender
- *
- *  Input parameters:
- *    the_semaphore            - the semaphore to be flushed
- *    id                       - id of parent semaphore
- *    api_semaphore_mp_support - api dependent MP support actions
- *
- *  Output parameters:
- *    CORE_SEMAPHORE_STATUS_SUCCESSFUL - if successful
- *    core error code                  - if unsuccessful
- *
- *  Output parameters:
- */
-
 CORE_semaphore_Status _CORE_semaphore_Surrender(
   CORE_semaphore_Control                *the_semaphore,
   Objects_Id                             id,
diff --git a/cpukit/score/src/coretod.c b/cpukit/score/src/coretod.c
index 1784a897a4..0cde95bbbe 100644
--- a/cpukit/score/src/coretod.c
+++ b/cpukit/score/src/coretod.c
@@ -1,5 +1,9 @@
-/*
- *  Time of Day (TOD) Handler
+/**
+ * @file
+ *
+ * @brief Initializes the Time of Day Handler
+ *
+ * @ingroup ScoreTODConstants
  */
 
 /*  COPYRIGHT (c) 1989-2008.
@@ -20,16 +24,6 @@
 #include <rtems/score/tod.h>
 #include <rtems/score/watchdog.h>
 
-/*
- *  _TOD_Handler_initialization
- *
- *  This routine initializes the time of day handler.
- *
- *  Input parameters:  NONE
- *
- *  Output parameters: NONE
- */
-
 void _TOD_Handler_initialization(void)
 {
   /* POSIX format TOD (timespec) */
diff --git a/cpukit/score/src/objectgetinfoid.c b/cpukit/score/src/objectgetinfoid.c
index b8bdbaf1ff..b6b13534b4 100644
--- a/cpukit/score/src/objectgetinfoid.c
+++ b/cpukit/score/src/objectgetinfoid.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Get Information of an Object from an ID
+ *
+ * @ingroup Score
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/objectnamespaceremove.c b/cpukit/score/src/objectnamespaceremove.c
index 97ee95f7e5..cd618457a4 100644
--- a/cpukit/score/src/objectnamespaceremove.c
+++ b/cpukit/score/src/objectnamespaceremove.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Removes Object from Namespace
+ *
+ * @ingroup Score
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulercbssetparameters.c b/cpukit/score/src/schedulercbssetparameters.c
index 49774cce7d..5bbf866e82 100644
--- a/cpukit/score/src/schedulercbssetparameters.c
+++ b/cpukit/score/src/schedulercbssetparameters.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Set Parameters for CBS Scheduling
+ *
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulercbsunblock.c b/cpukit/score/src/schedulercbsunblock.c
index 19578628b2..529d571dbf 100644
--- a/cpukit/score/src/schedulercbsunblock.c
+++ b/cpukit/score/src/schedulercbsunblock.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Unblocks a Thread from the Queue
+ *
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/scheduleredfenqueuefirst.c b/cpukit/score/src/scheduleredfenqueuefirst.c
index 8ad0d139ce..9f99140ea0 100644
--- a/cpukit/score/src/scheduleredfenqueuefirst.c
+++ b/cpukit/score/src/scheduleredfenqueuefirst.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Enqueues a thread to the ready queue
+ *
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/scheduleredfyield.c b/cpukit/score/src/scheduleredfyield.c
index ff68838b47..d6862540a0 100644
--- a/cpukit/score/src/scheduleredfyield.c
+++ b/cpukit/score/src/scheduleredfyield.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Scheduler EDF Yield
+ *
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/threadloadenv.c b/cpukit/score/src/threadloadenv.c
index d2dd049016..6cce54fb1a 100644
--- a/cpukit/score/src/threadloadenv.c
+++ b/cpukit/score/src/threadloadenv.c
@@ -1,7 +1,12 @@
-/*
- *  Thread Handler
+/**
+ * @file
  *
+ * @brief Initializes Enviroment for A Thread
  *
+ * @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -27,18 +32,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  _Thread_Load_environment
- *
- *  Load starting environment for another thread from its start area in the
- *  thread.  Only called from t_restart and t_start.
- *
- *  Input parameters:
- *    the_thread - thread control block pointer
- *
- *  Output parameters:  NONE
- */
-
 void _Thread_Load_environment(
   Thread_Control *the_thread
 )
diff --git a/cpukit/score/src/threadsetstate.c b/cpukit/score/src/threadsetstate.c
index 1372b5d919..f72cdec750 100644
--- a/cpukit/score/src/threadsetstate.c
+++ b/cpukit/score/src/threadsetstate.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Sets States for a Thread
+ *
+ * @ingroup ScoreThread
+ */
+
 /*
  *  Thread Handler / Thread Set State
  *
@@ -27,11 +35,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  INTERRUPT LATENCY:
- *    ready chain
- *    select map
- */
 void _Thread_Set_state(
   Thread_Control *the_thread,
   States_Control  state
diff --git a/cpukit/score/src/threadstart.c b/cpukit/score/src/threadstart.c
index 550404a2e4..d9ce62a091 100644
--- a/cpukit/score/src/threadstart.c
+++ b/cpukit/score/src/threadstart.c
@@ -1,7 +1,12 @@
-/*
- *  Thread Handler
+/**
+ * @file
  *
+ * @brief Initializes Thread and Executes it
  *
+ * @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,16 +33,6 @@
 #include <rtems/score/userextimpl.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  _Thread_Start
- *
- *  DESCRIPTION:
- *
- *  This routine initializes the executable information for a thread
- *  and makes it ready to execute.  After this routine executes, the
- *  thread competes with all other threads for CPU time.
- */
-
 bool _Thread_Start(
   Thread_Control            *the_thread,
   Thread_Start_types         the_prototype,
diff --git a/cpukit/score/src/ts64set.c b/cpukit/score/src/ts64set.c
index 16e3d7beac..d06755d5f1 100644
--- a/cpukit/score/src/ts64set.c
+++ b/cpukit/score/src/ts64set.c
@@ -1,6 +1,10 @@
 /**
- * @file score/src/ts64set.c
-*/
+ * @file
+ *
+ * @brief Set Timestamp to Specified Seconds and Nanoseconds
+ *
+ * @ingroup SuperCore
+ */
 
 /*
  *  COPYRIGHT (c) 1989-2008.
diff --git a/cpukit/score/src/ts64totimespec.c b/cpukit/score/src/ts64totimespec.c
index 69640fdf70..051fb2762b 100644
--- a/cpukit/score/src/ts64totimespec.c
+++ b/cpukit/score/src/ts64totimespec.c
@@ -1,6 +1,10 @@
 /**
- * @file score/src/ts64totimespec.c
-*/
+ * @file
+ *
+ * @brief Convert Timestamp to Struct Timespec
+ *
+ * @ingroup SuperCore
+ */
 
 /*
  *  COPYRIGHT (c) 1989-2008.