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

20 files changed, 154 insertions, 141 deletions

diff --git a/cpukit/score/src/chain.c b/cpukit/score/src/chain.c
index fb3916c285..7e63107876 100644
--- a/cpukit/score/src/chain.c
+++ b/cpukit/score/src/chain.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Initialize a Chain Header
+ *
+ * @ingroup ScoreChain
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -16,20 +24,6 @@
 #include <rtems/score/chain.h>
 #include <rtems/score/isr.h>
 
-/*
- *  _Chain_Initialize
- *
- *  This kernel routine initializes a doubly linked chain.
- *
- *  Input parameters:
- *    the_chain        - pointer to chain header
- *    starting_address - starting address of first node
- *    number_nodes     - number of nodes in chain
- *    node_size        - size of node in bytes
- *
- *  Output parameters:  NONE
- */
-
 void _Chain_Initialize(
   Chain_Control *the_chain,
   void           *starting_address,
diff --git a/cpukit/score/src/coremsgsubmit.c b/cpukit/score/src/coremsgsubmit.c
index 1ce496ed88..8f6ffa31d5 100644
--- a/cpukit/score/src/coremsgsubmit.c
+++ b/cpukit/score/src/coremsgsubmit.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 CORE Message Queue Submit
  *
+ * @ingroup ScoreMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,29 +28,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  _CORE_message_queue_Submit
- *
- *  This routine implements the send and urgent message functions. It
- *  processes a message that is to be submitted to the designated
- *  message queue.  The message will either be processed as a
- *  send message which it will be inserted at the rear of the queue
- *  or it will be processed as an urgent message which will be inserted
- *  at the front of the queue.
- *
- *  Input parameters:
- *    the_message_queue            - message is submitted to this message queue
- *    buffer                       - pointer to message buffer
- *    size                         - size in bytes of message to send
- *    id                           - id of message queue
- *    api_message_queue_mp_support - api specific mp support callout
- *    submit_type                  - send or urgent message
- *
- *  Output parameters:
- *    CORE_MESSAGE_QUEUE_SUCCESSFUL - if successful
- *    error code                    - if unsuccessful
- */
-
 CORE_message_queue_Status _CORE_message_queue_Submit(
   CORE_message_queue_Control                *the_message_queue,
   const void                                *buffer,
diff --git a/cpukit/score/src/coretodset.c b/cpukit/score/src/coretodset.c
index 8b0928af60..57a7d45d37 100644
--- a/cpukit/score/src/coretodset.c
+++ b/cpukit/score/src/coretodset.c
@@ -1,5 +1,9 @@
-/*
- *  Time of Day (TOD) Handler -- Set Time
+/**
+ * @file
+ *
+ * @brief Set Time of Day Given a Timestamp
+ *
+ * @ingroup ScoreTOD
  */
 
 /*  COPYRIGHT (c) 1989-2007.
diff --git a/cpukit/score/src/coretodtickle.c b/cpukit/score/src/coretodtickle.c
index d0412f85d4..e464db3b52 100644
--- a/cpukit/score/src/coretodtickle.c
+++ b/cpukit/score/src/coretodtickle.c
@@ -1,5 +1,9 @@
-/*
- *  Time of Day (TOD) Handler -- Tickle Ticks
+/**
+ * @file
+ *
+ * @brief Increments time of day at each clock tick
+ *
+ * @ingroup ScoreTODConstants
  */
 
 /*  COPYRIGHT (c) 1989-2007.
@@ -22,16 +26,6 @@
 #include <rtems/score/watchdog.h>
 #include <rtems/config.h>
 
-/*
- *  _TOD_Tickle_ticks
- *
- *  This routine processes a clock tick.
- *
- *  Input parameters: NONE
- *
- *  Output parameters: NONE
- */
-
 void _TOD_Tickle_ticks( void )
 {
   Timestamp_Control tick;
diff --git a/cpukit/score/src/coretodusectoticks.c b/cpukit/score/src/coretodusectoticks.c
index 2189a45ca3..60d08b9280 100644
--- a/cpukit/score/src/coretodusectoticks.c
+++ b/cpukit/score/src/coretodusectoticks.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Converts Microseconds to Ticks
+ *
+ * @ingroup ScoreTOD
+ */
+
 /*  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/schedulercbsgetexecutiontime.c b/cpukit/score/src/schedulercbsgetexecutiontime.c
index a16fdc912c..c2c0a3ef23 100644
--- a/cpukit/score/src/schedulercbsgetexecutiontime.c
+++ b/cpukit/score/src/schedulercbsgetexecutiontime.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Get Thread Execution Info
+ *
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/scheduleredfblock.c b/cpukit/score/src/scheduleredfblock.c
index 3efd618f86..1eb6c29931 100644
--- a/cpukit/score/src/scheduleredfblock.c
+++ b/cpukit/score/src/scheduleredfblock.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Removes the Thread from Ready Queue
+ *
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/scheduleredffree.c b/cpukit/score/src/scheduleredffree.c
index 556723c887..a26f971f21 100644
--- a/cpukit/score/src/scheduleredffree.c
+++ b/cpukit/score/src/scheduleredffree.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Frees EDF Thread Information
+ *
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulerpriorityextract.c b/cpukit/score/src/schedulerpriorityextract.c
index 1db27565dc..02f6004d28 100644
--- a/cpukit/score/src/schedulerpriorityextract.c
+++ b/cpukit/score/src/schedulerpriorityextract.c
@@ -1,5 +1,12 @@
-/*  Scheduler Simple Handler / Extract
+/**
+ * @file
  *
+ * @brief Removes Thread from Thread Queue
+ *
+ * @ingroup ScoreScheduler
+ */
+
+/*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/schedulersimple.c b/cpukit/score/src/schedulersimple.c
index 9b875988d6..6ba46a36b2 100644
--- a/cpukit/score/src/schedulersimple.c
+++ b/cpukit/score/src/schedulersimple.c
@@ -1,9 +1,12 @@
-/*
- *  Scheduler Simple Handler / Initialize
- *  Scheduler Simple Handler / Allocate (Empty Routine)
- *  Scheduler Simple Handler / Update (Empty Routine)
- *  Scheduler Simple Handler / Free (Empty Routine)
+/**
+ * @file
+ *
+ * @brief Scheduler Simple Functions
  *
+ * @ingroup ScoreScheduler
+ */
+
+/*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,14 +27,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/wkspace.h>
 
-/**
- * This routine does nothing, and is used as a stub for Schedule allocate
- *
- * Note: returns a non-zero value, or else thread initialize thinks the
- * allocation failed.
- *
- * The overhead of a function call will still be imposed.
- */
 void * _Scheduler_simple_Allocate(
   Thread_Control *the_thread
 )
@@ -39,32 +34,18 @@ void * _Scheduler_simple_Allocate(
   return (void*)-1; /* maybe pick an appropriate poison value */
 }
 
-
-/**
- * This routine does nothing, and is used as a stub for Schedule update
- *
- * The overhead of a function call will still be imposed.
- */
 void _Scheduler_simple_Update(
   Thread_Control *the_thread
 )
 {
 }
 
-/**
- * This routine does nothing, and is used as a stub for Schedule free
- *
- * The overhead of a function call will still be imposed.
- */
 void _Scheduler_simple_Free(
   Thread_Control *the_thread
 )
 {
 }
 
-/**
- * This routine initializes the simple scheduler.
- */
 void _Scheduler_simple_Initialize ( void )
 {
   void *f;
diff --git a/cpukit/score/src/schedulersimpleenqueue.c b/cpukit/score/src/schedulersimpleenqueue.c
index c0f47829d4..4288491c04 100644
--- a/cpukit/score/src/schedulersimpleenqueue.c
+++ b/cpukit/score/src/schedulersimpleenqueue.c
@@ -1,6 +1,12 @@
-/*
- *  Schedule Simple Handler / Enqueue
+/**
+ * @file
+ *
+ * @brief Puts Thread onto the Ready Queue
  *
+ * @ingroup ScoreScheduler
+ */
+
+/*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/schedulersimpleextract.c b/cpukit/score/src/schedulersimpleextract.c
index eeeade9159..e5d6e78e2f 100644
--- a/cpukit/score/src/schedulersimpleextract.c
+++ b/cpukit/score/src/schedulersimpleextract.c
@@ -1,6 +1,12 @@
-/*
- *  Schedule Simple Handler / Extract
+/**
+ * @file
+ *
+ * @brief Removes a Thread from the Simple Queue
  *
+ * @ingroup ScoreScheduler
+ */
+
+/*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/threadchangepriority.c b/cpukit/score/src/threadchangepriority.c
index 6ab096658e..82b8efb721 100644
--- a/cpukit/score/src/threadchangepriority.c
+++ b/cpukit/score/src/threadchangepriority.c
@@ -1,6 +1,12 @@
-/*
- *  Thread Handler / Change Priority
+/**
+ * @file
+ *
+ * @brief Changes the Priority of a Thread
  *
+ * @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/threaddispatchdisablelevel.c b/cpukit/score/src/threaddispatchdisablelevel.c
index 15e2f6d215..36be088663 100644
--- a/cpukit/score/src/threaddispatchdisablelevel.c
+++ b/cpukit/score/src/threaddispatchdisablelevel.c
@@ -1,6 +1,12 @@
-/*
- *  Thread Dispatch Disable Level Methods
+/**
+ * @file
+ *
+ * @brief Thread Dispatch Disable Functions
  *
+ * @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/threadenabledispatch.c b/cpukit/score/src/threadenabledispatch.c
index 0acb7cedd5..7d21789984 100644
--- a/cpukit/score/src/threadenabledispatch.c
+++ b/cpukit/score/src/threadenabledispatch.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Enable Dispatching of Threads
+ *
+ * @ingroup ScoreThread
+ */
+
 /*
  *   _Thread_Enable_dispatch
  *
@@ -20,23 +28,6 @@
   #include <rtems/score/timestamp.h>
 #endif
 
-
-/**
- *  The following declares the dispatch critical section nesting
- *  counter which is used to prevent context switches at inopportune
- *  moments.
- */
-
-/**
- *  _Thread_Enable_dispatch
- *
- *  This kernel routine exits a context switch disable critical section.
- *  This is the NOT INLINED version.
- *
- *  INTERRUPT LATENCY:
- *    dispatch thread
- *    no dispatch thread
- */
 #if defined (__THREAD_DO_NOT_INLINE_ENABLE_DISPATCH__ )
 void _Thread_Enable_dispatch( void )
 {
diff --git a/cpukit/score/src/threadqextract.c b/cpukit/score/src/threadqextract.c
index 94e41df8c7..3b6aac58de 100644
--- a/cpukit/score/src/threadqextract.c
+++ b/cpukit/score/src/threadqextract.c
@@ -1,7 +1,12 @@
-/*
- *  Thread Queue Handler
+/**
+ * @file
  *
+ * @brief Extracts Thread from Thread Queue
  *
+ * @ingroup ScoreThreadQ
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,21 +28,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/tqdata.h>
 
-/*
- *  _Thread_queue_Extract
- *
- *  This routine removes a specific thread from the specified threadq,
- *  deletes any timeout, and unblocks the thread.
- *
- *  Input parameters:
- *    the_thread_queue - pointer to a threadq header
- *    the_thread       - pointer to a thread control block
- *
- *  Output parameters: NONE
- *
- *  INTERRUPT LATENCY: NONE
- */
-
 void _Thread_queue_Extract(
   Thread_queue_Control *the_thread_queue,
   Thread_Control       *the_thread
diff --git a/cpukit/score/src/threadqfirstpriority.c b/cpukit/score/src/threadqfirstpriority.c
index c14f382b08..eefc88b168 100644
--- a/cpukit/score/src/threadqfirstpriority.c
+++ b/cpukit/score/src/threadqfirstpriority.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Returns Highest Priority Thread on Thread Queue
+ *
+ * @ingroup ScoreThreadQ
+ */
+
 /*
  *  Thread Queue Handler
  *
@@ -23,19 +31,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/tqdata.h>
 
-/*
- *  _Thread_queue_First_priority
- *
- *  This routines returns a pointer to the first thread on the
- *  specified threadq.
- *
- *  Input parameters:
- *    the_thread_queue - pointer to thread queue
- *
- *  Output parameters:
- *    returns - first thread or NULL
- */
-
 Thread_Control *_Thread_queue_First_priority (
   Thread_queue_Control *the_thread_queue
 )
diff --git a/cpukit/score/src/ts64totimeval.c b/cpukit/score/src/ts64totimeval.c
index 29bbb7895c..16c75a025e 100644
--- a/cpukit/score/src/ts64totimeval.c
+++ b/cpukit/score/src/ts64totimeval.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Convert 64-bit Timestamp to struct timeval
+ *
+ * @ingroup SuperCore
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/score/src/userextiterate.c b/cpukit/score/src/userextiterate.c
index 7dd2ab3a11..299116bda0 100644
--- a/cpukit/score/src/userextiterate.c
+++ b/cpukit/score/src/userextiterate.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief User Extension Iteration Helpers
+ *
+ * @ingroup ScoreUserExt
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/score/src/wkstringduplicate.c b/cpukit/score/src/wkstringduplicate.c
index 00aa3a3e11..2b33cb1a55 100644
--- a/cpukit/score/src/wkstringduplicate.c
+++ b/cpukit/score/src/wkstringduplicate.c
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Duplicates String with Memory from the Workspace
+ *
+ * @ingroup ScoreWorkspace
+ */
+
 /*
  * Copyright (c) 2011 embedded brains GmbH.  All rights reserved.
  *