score misc: Score misc: Clean up Doxygen #7 (GCI 2012)

    This patch is a task from GCI 2012 which improves the Doxygen
    comments in the RTEMS source.

https://google-melange.appspot.com/gci/task/view/google/gci2012/7986214

20 files changed, 137 insertions, 183 deletions

diff --git a/cpukit/score/src/objectallocate.c b/cpukit/score/src/objectallocate.c
index 23debcad8f..15db8d38fb 100644
--- a/cpukit/score/src/objectallocate.c
+++ b/cpukit/score/src/objectallocate.c
@@ -1,7 +1,11 @@
-/*
- *  Object Handler
- *
+/**
+ *  @file
  *
+ *  @brief Allocate Object
+ *  @ingroup ScoreObject
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -32,15 +36,6 @@
 #include <rtems/bspIo.h>
 #endif
 
-/*
- *  _Objects_Allocate
- *
- *  DESCRIPTION:
- *
- *  This function allocates a object control block from
- *  the inactive chain of free object control blocks.
- */
-
 Objects_Control *_Objects_Allocate(
   Objects_Information *information
 )
diff --git a/cpukit/score/src/objectapimaximumclass.c b/cpukit/score/src/objectapimaximumclass.c
index 7c032a1844..4cd54d8efe 100644
--- a/cpukit/score/src/objectapimaximumclass.c
+++ b/cpukit/score/src/objectapimaximumclass.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Object API Maximum Class
+ *  @ingroup ScoreObject
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/objectclose.c b/cpukit/score/src/objectclose.c
index f5db97f447..e669504782 100644
--- a/cpukit/score/src/objectclose.c
+++ b/cpukit/score/src/objectclose.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Close Object
+ *  @ingroup ScoreObject
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/objectgetisr.c b/cpukit/score/src/objectgetisr.c
index c674af7e92..4a281c2b23 100644
--- a/cpukit/score/src/objectgetisr.c
+++ b/cpukit/score/src/objectgetisr.c
@@ -1,7 +1,11 @@
-/*
- *  Object Handler
- *
+/**
+ *  @file
  *
+ *  @brief Object Get Isr Disable
+ *  @ingroup ScoreObject
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -26,27 +30,6 @@
 #include <rtems/score/sysstate.h>
 #include <rtems/score/isr.h>
 
-/*
- * _Objects_Get_isr_disable
- *
- * 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
- *   level       - pointer to previous interrupt level
- *
- * 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
- *  *level    - previous interrupt level
- */
-
 Objects_Control *_Objects_Get_isr_disable(
   Objects_Information *information,
   Objects_Id           id,
diff --git a/cpukit/score/src/objectmp.c b/cpukit/score/src/objectmp.c
index 582194c3ac..44319b9363 100644
--- a/cpukit/score/src/objectmp.c
+++ b/cpukit/score/src/objectmp.c
@@ -1,7 +1,11 @@
-/*
- *  Multiprocessing Support for the Object Handler
- *
+/**
+ *  @file
  *
+ *  @brief Objects MP Support
+ *  @ingroup ScoreObjectMP
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,10 +25,6 @@
 #include <rtems/score/wkspace.h>
 #include <rtems/score/thread.h>
 
-/*
- *  _Objects_MP_Handler_early_initialization
- *
- */
 void _Objects_MP_Handler_early_initialization(void)
 {
   uint32_t   node;
@@ -74,11 +74,6 @@ void _Objects_MP_Handler_initialization(void)
 
 }
 
-/*
- *  _Objects_MP_Open
- *
- */
-
 void _Objects_MP_Open (
   Objects_Information *information,
   Objects_MP_Control  *the_global_object,
@@ -96,11 +91,6 @@ void _Objects_MP_Open (
 
 }
 
-/*
- *  _Objects_MP_Allocate_and_open
- *
- */
-
 bool _Objects_MP_Allocate_and_open (
   Objects_Information *information,
   uint32_t             the_name,      /* XXX -- wrong for variable */
@@ -129,11 +119,6 @@ bool _Objects_MP_Allocate_and_open (
   return true;
 }
 
-/*
- *  _Objects_MP_Close
- *
- */
-
 void _Objects_MP_Close (
   Objects_Information *information,
   Objects_Id           the_id
@@ -167,11 +152,6 @@ void _Objects_MP_Close (
   );
 }
 
-/*
- *  _Objects_MP_Global_name_search
- *
- */
-
 Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search (
   Objects_Information *information,
   Objects_Name         the_name,
@@ -235,11 +215,6 @@ Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search (
   return OBJECTS_INVALID_NAME;
 }
 
-/*
- *  _Objects_MP_Is_remote
- *
- */
-
 void _Objects_MP_Is_remote (
   Objects_Information  *information,
   Objects_Id            the_id,
diff --git a/cpukit/score/src/rbtree.c b/cpukit/score/src/rbtree.c
index 48ea2a0a4f..59dfd760c2 100644
--- a/cpukit/score/src/rbtree.c
+++ b/cpukit/score/src/rbtree.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Initialize a RBTree Header
+ *  @ingroup ScoreRBTree
+ */
+
 /*
  *  Copyright (c) 2010 Gedare Bloom.
  *
@@ -15,20 +22,6 @@
 #include <rtems/score/rbtree.h>
 #include <rtems/score/isr.h>
 
-/*
- *  _RBTree_Initialize
- *
- *  This kernel routine initializes a Red-Black Tree.
- *
- *  Input parameters:
- *    the_rbtree        - pointer to rbtree header
- *    starting_address - starting address of first node
- *    number_nodes     - number of nodes in rbtree
- *    node_size        - size of node in bytes
- *
- *  Output parameters:  NONE
- */
-
 void _RBTree_Initialize(
   RBTree_Control          *the_rbtree,
   RBTree_Compare_function  compare_function,
diff --git a/cpukit/score/src/scheduleredfextract.c b/cpukit/score/src/scheduleredfextract.c
index e9ef0a4906..7547cafcb9 100644
--- a/cpukit/score/src/scheduleredfextract.c
+++ b/cpukit/score/src/scheduleredfextract.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Scheduler EDF Extract
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulerpriorityallocate.c b/cpukit/score/src/schedulerpriorityallocate.c
index 221373a2d7..8c2291fa7a 100644
--- a/cpukit/score/src/schedulerpriorityallocate.c
+++ b/cpukit/score/src/schedulerpriorityallocate.c
@@ -1,6 +1,11 @@
-/*
- *  Scheduler Priority Handler / Allocate
+/**
+ *  @file
  *
+ *  @brief Allocate Scheduler Priority
+ *  @ingroup ScoreScheduler
+ */
+
+/*
  *  Copyright (C) 2010 Gedare Bloom.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/schedulerpriorityenqueuefirst.c b/cpukit/score/src/schedulerpriorityenqueuefirst.c
index 9081803ce1..f5b4940693 100644
--- a/cpukit/score/src/schedulerpriorityenqueuefirst.c
+++ b/cpukit/score/src/schedulerpriorityenqueuefirst.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Scheduler Priority Enqueue First
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulersimplereadyqueueenqueuefirst.c b/cpukit/score/src/schedulersimplereadyqueueenqueuefirst.c
index 2882034bf0..47a4a3be64 100644
--- a/cpukit/score/src/schedulersimplereadyqueueenqueuefirst.c
+++ b/cpukit/score/src/schedulersimplereadyqueueenqueuefirst.c
@@ -1,6 +1,11 @@
-/*
- *  Schedule Simple Handler / Ready Queue Enqueue First
+/**
+ *  @file
  *
+ *  @brief Scheduler Simple Ready Queue Enqueue First
+ *  @ingroup ScoreScheduler
+ */
+
+/*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/threadclose.c b/cpukit/score/src/threadclose.c
index 6fc72b5cb0..05abcefa61 100644
--- a/cpukit/score/src/threadclose.c
+++ b/cpukit/score/src/threadclose.c
@@ -1,6 +1,11 @@
-/*
- *  Thread Handler / Thread Close
+/**
+ *  @file
  *
+ *  @brief Thread Close
+ *  @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/score/src/threadq.c b/cpukit/score/src/threadq.c
index 2a7449fa78..900a3f6b03 100644
--- a/cpukit/score/src/threadq.c
+++ b/cpukit/score/src/threadq.c
@@ -1,7 +1,11 @@
-/*
- *  Thread Queue Handler
- *
+/**
+ *  @file
  *
+ *  @brief Thread Queue Initialize
+ *  @ingroup ScoreThreadQ
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,20 +27,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/tqdata.h>
 
-/*
- *  _Thread_queue_Initialize
- *
- *  This routine initializes the specified threadq.
- *
- *  Input parameters:
- *    the_thread_queue      - pointer to a threadq header
- *    discipline            - queueing discipline
- *    state                 - state of waiting threads
- *    timeout_status        - return on a timeout
- *
- *  Output parameters: NONE
- */
-
 void _Thread_queue_Initialize(
   Thread_queue_Control         *the_thread_queue,
   Thread_queue_Disciplines      the_discipline,
diff --git a/cpukit/score/src/threadqenqueuepriority.c b/cpukit/score/src/threadqenqueuepriority.c
index 687187e56a..d367a40554 100644
--- a/cpukit/score/src/threadqenqueuepriority.c
+++ b/cpukit/score/src/threadqenqueuepriority.c
@@ -1,6 +1,11 @@
-/*
- *  Thread Queue Handler - Enqueue By Priority
+/**
+ *  @file
  *
+ *  @brief Thread Queue Enqueue Priority
+ *  @ingroup ScoreThreadQ
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -30,22 +35,6 @@
   #define CPU_UNROLL_ENQUEUE_PRIORITY FALSE
 #endif
 
-/*
- *  _Thread_queue_Enqueue_priority
- *
- *  This routine places a blocked thread on a priority thread queue.
- *
- *  Input parameters:
- *    the_thread_queue - pointer to threadq
- *    thread           - thread to insert
- *
- *  Output parameters: NONE
- *
- *  INTERRUPT LATENCY:
- *    forward less than
- *    forward equal
- */
-
 Thread_blocking_operation_States _Thread_queue_Enqueue_priority (
   Thread_queue_Control *the_thread_queue,
   Thread_Control       *the_thread,
diff --git a/cpukit/score/src/threadqfirst.c b/cpukit/score/src/threadqfirst.c
index ddbd969845..ef8a13175d 100644
--- a/cpukit/score/src/threadqfirst.c
+++ b/cpukit/score/src/threadqfirst.c
@@ -1,7 +1,11 @@
-/*
- *  Thread Queue Handler
- *
+/**
+ *  @file
  *
+ *  @brief Thread Queue First
+ *  @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_First
- *
- *  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(
   Thread_queue_Control *the_thread_queue
 )
diff --git a/cpukit/score/src/threadqtimeout.c b/cpukit/score/src/threadqtimeout.c
index ee279e6595..c1f62cf5a7 100644
--- a/cpukit/score/src/threadqtimeout.c
+++ b/cpukit/score/src/threadqtimeout.c
@@ -1,7 +1,11 @@
-/*
- *  Thread Queue Handler
- *
+/**
+ *  @file
  *
+ *  @brief Thread Queue Timeout
+ *  @ingroup ScoreThreadQ
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,18 +27,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/tqdata.h>
 
-/*
- *  _Thread_queue_Timeout
- *
- *  This routine processes a thread which timeouts while waiting on
- *  a thread queue. It is called by the watchdog handler.
- *
- *  Input parameters:
- *    id - thread id
- *
- *  Output parameters: NONE
- */
-
 void _Thread_queue_Timeout(
   Objects_Id  id,
   void       *ignored __attribute__((unused))
diff --git a/cpukit/score/src/threadready.c b/cpukit/score/src/threadready.c
index 0eb00e6c05..d1e57a431a 100644
--- a/cpukit/score/src/threadready.c
+++ b/cpukit/score/src/threadready.c
@@ -1,6 +1,11 @@
-/*
- *  Thread Handler / Thread Ready
+/**
+ *  @file
  *
+ *  @brief Thread Ready
+ *  @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -27,11 +32,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  INTERRUPT LATENCY:
- *    ready chain
- *    select heir
- */
 void _Thread_Ready(
   Thread_Control *the_thread
 )
diff --git a/cpukit/score/src/timespecfromticks.c b/cpukit/score/src/timespecfromticks.c
index db9c32c52d..dc11fbf3cd 100644
--- a/cpukit/score/src/timespecfromticks.c
+++ b/cpukit/score/src/timespecfromticks.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Convert Ticks to Timespec
+ *  @ingroup Timespec
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/timespecisvalid.c b/cpukit/score/src/timespecisvalid.c
index 26c5102017..4a0a247ba9 100644
--- a/cpukit/score/src/timespecisvalid.c
+++ b/cpukit/score/src/timespecisvalid.c
@@ -1,5 +1,8 @@
 /**
- *  @file  score/src/timespecisvalid.c
+ *  @file
+ *
+ *  @brief Is Timespec Valid
+ *  @ingroup Timespec
  */
 
 /*
diff --git a/cpukit/score/src/watchdog.c b/cpukit/score/src/watchdog.c
index 987928e44c..9e32b9c4c3 100644
--- a/cpukit/score/src/watchdog.c
+++ b/cpukit/score/src/watchdog.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Watchdog Handler Initialization
+ *  @ingroup ScoreWatchdog
+ */
+
 /*
  *  Watchdog Handler
  *
@@ -18,16 +25,6 @@
 #include <rtems/score/isr.h>
 #include <rtems/score/watchdog.h>
 
-/*
- *  _Watchdog_Handler_initialization
- *
- *  This routine initializes the watchdog handler.
- *
- *  Input parameters:  NONE
- *
- *  Output parameters: NONE
- */
-
 void _Watchdog_Handler_initialization( void )
 {
   _Watchdog_Sync_count = 0;
diff --git a/cpukit/score/src/wkspace.c b/cpukit/score/src/wkspace.c
index 7e58585173..72712456fa 100644
--- a/cpukit/score/src/wkspace.c
+++ b/cpukit/score/src/wkspace.c
@@ -1,6 +1,11 @@
-/*
- *  Workspace Handler
+/**
+ *  @file
  *
+ *  @brief Workspace Handler Support
+ *  @ingroup ScoreWorkspace
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -25,9 +30,6 @@
   #include <rtems/bspIo.h>
 #endif
 
-/*
- *  _Workspace_Handler_initialization
- */
 void _Workspace_Handler_initialization(
   Heap_Area *areas,
   size_t area_count,
@@ -93,9 +95,6 @@ void _Workspace_Handler_initialization(
   }
 }
 
-/*
- *  _Workspace_Allocate
- */
 void *_Workspace_Allocate(
   size_t   size
 )
@@ -133,9 +132,6 @@ void _Workspace_Free(
   _Heap_Free( &_Workspace_Area, block );
 }
 
-/*
- *  _Workspace_Allocate_or_fatal_error
- */
 void *_Workspace_Allocate_or_fatal_error(
   size_t      size
 )