score misc: Clean up Doxygen #3 (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/7982215

cpukit/score/include/rtems/score/coremsg.h

@@ -257,8 +257,15 @@ typedef struct {
 
 /**
  *  @brief Initialize a Message Queue
+ * 
+ *  DESCRIPTION:
  *
- *  This routine initializes @a the_message_queue based on the parameters passed.
+ *  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.
+ *
+ *  This routine initializes @a the_message_queue 
+ *      based on the parameters passed.
  *
  *  @param[in] the_message_queue points to the message queue to initialize
  *  @param[in] the_message_queue_attributes points to the attributes that

cpukit/score/include/rtems/score/coresem.h

@@ -127,6 +127,14 @@ typedef struct {
 }   CORE_semaphore_Control;
 
 /**
+ *  @brief Core Semaphore Initialize
+ * 
+ *  DESCRIPTION:
+ *
+ *  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.
+ * 
  *  This routine initializes the semaphore based on the parameters passed.
  *
  *  @param[in] the_semaphore is the semaphore to initialize

cpukit/score/include/rtems/score/object.h

@@ -697,6 +697,8 @@ 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

cpukit/score/include/rtems/score/schedulerpriority.h

@@ -121,6 +121,8 @@ void _Scheduler_priority_Update(
 );
 
 /**
+ *  @brief Scheduler Priority Unblock
+ * 
  *  This routine adds @a the_thread to the scheduling decision,
  *  that is, adds it to the ready queue and
  *  updates any appropriate scheduling variables, for example the heir thread.

cpukit/score/include/rtems/score/schedulersimple.h

@@ -119,6 +119,8 @@ 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.
  *

cpukit/score/include/rtems/score/thread.h

@@ -708,6 +708,8 @@ void _Thread_Change_priority (
 );
 
 /**
+ *  @brief Set Thread Priority
+ *  
  *  This routine updates the priority related fields in the_thread
  *  control block to indicate the current priority is now new_priority.
  */

cpukit/score/include/rtems/score/threadq.h

@@ -109,6 +109,9 @@ void _Thread_queue_Enqueue_with_handler(
  *  the_thread is removed from the_thread_queue and reinserted using
  *  its new priority.  This method has no impact on the state of the_thread
  *  or of any timeouts associated with this blocking.
+ * 
+ *  @param[in] the_thread_queue pointer to a threadq header
+ *  @param[in] the_thread pointer to a thread control block
  */
 void _Thread_queue_Requeue(
   Thread_queue_Control *the_thread_queue,
@@ -254,6 +257,13 @@ Thread_Control *_Thread_queue_Dequeue_fifo(
  *  This routine enqueues the currently executing thread on
  *  the_thread_queue with an optional timeout using the
  *  FIFO discipline.
+ * 
+ *    @param[in] the_thread_queue pointer to threadq
+ *    @param[in] the_thread pointer to the thread to block
+ *    @param[in] level_p interrupt level in case the operation blocks actually
+ * 
+ *  - INTERRUPT LATENCY:
+ *    + single case
  */
 Thread_blocking_operation_States _Thread_queue_Enqueue_fifo (
   Thread_queue_Control *the_thread_queue,

cpukit/score/src/coremsg.c

@@ -1,12 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief Initialize a Message Queue
+ *  @ingroup ScoreMessageQueue
+ */
+
 /*
- *  CORE Message Queue Handler
- *
- *  DESCRIPTION:
- *
- *  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.
- *
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -49,24 +48,6 @@ static inline bool size_t_mult32_with_overflow(
   return true;
 }
 
-/*
- *  _CORE_message_queue_Initialize
- *
- *  This routine initializes a newly created message queue based on the
- *  specified data.
- *
- *  Input parameters:
- *    the_message_queue            - the message queue to initialize
- *    the_class                    - the API specific object class
- *    the_message_queue_attributes - the message queue's attributes
- *    maximum_pending_messages     - maximum message and reserved buffer count
- *    maximum_message_size         - maximum size of each message
- *
- *  Output parameters:
- *    true   - if the message queue is initialized
- *    false  - if the message queue is NOT initialized
- */
-
 bool _CORE_message_queue_Initialize(
   CORE_message_queue_Control    *the_message_queue,
   CORE_message_queue_Attributes *the_message_queue_attributes,

cpukit/score/src/coresem.c

@@ -1,12 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief Core Semaphore Initialize
+ *  @ingroup ScoreSemaphore
+ */
+
 /*
- *  CORE Semaphore Handler
- *
- *  DESCRIPTION:
- *
- *  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.
- *
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -26,20 +25,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/threadq.h>
 
-/*
- *  CORE_semaphore_Initialize
- *
- *  This function initialize a semaphore and sets the initial value based
- *  on the given count.
- *
- *  Input parameters:
- *    the_semaphore            - the semaphore control block to initialize
- *    the_semaphore_attributes - the attributes specified at create time
- *    initial_value            - semaphore's initial value
- *
- *  Output parameters:  NONE
- */
-
 void _CORE_semaphore_Initialize(
   CORE_semaphore_Control       *the_semaphore,
   CORE_semaphore_Attributes    *the_semaphore_attributes,

cpukit/score/src/coretodget.c

@@ -1,6 +1,11 @@
-/*
- *  Time of Day (TOD) Handler - get TOD
+/**
+ *  @file
  *
+ *  @brief Returns a Current TOD with Nanosecond Granularity
+ *  @ingroup ScoreTODConstants
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/score/src/coretodtickspersec.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Convert Ticks To Seconds
+ *  @ingroup ScoreTODConstants
+ */
+
 /*  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/score/src/objectgetnoprotection.c

@@ -1,7 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief  Get Object without Dispatching Protection
+ *  @ingroup ScoreObject
+ */
+
 /*
- *  Object Handler -- Object Get
- *
- *
  *  COPYRIGHT (c) 1989-2002.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -26,25 +30,6 @@
 #include <rtems/score/sysstate.h>
 #include <rtems/score/isr.h>
 
-/*
- * _Objects_Get_no_protection
- *
- * 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
- *
- * 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
- */
-
 Objects_Control *_Objects_Get_no_protection(
   Objects_Information *information,
   Objects_Id           id,

cpukit/score/src/schedulercbscleanup.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Scheduler CBS Cleanup
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).

cpukit/score/src/schedulercbscreateserver.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Scheduler CBS Create Server
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).

cpukit/score/src/schedulercbsgetapprovedbudget.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Scheduler CBS Get Approved Budget
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).

cpukit/score/src/schedulercbsgetremainingbudget.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Scheduler CBS Get Remaining Budget
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).

cpukit/score/src/schedulerpriorityprioritycompare.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Scheduler Priority Compare Two Priorities
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).

cpukit/score/src/schedulerpriorityreleasejob.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Scheduler Priority Release Job
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).

cpukit/score/src/schedulerpriorityunblock.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Scheduler Priority Unblock
+ *  @ingroup ScoreScheduler
+ */
+
 /*
  *  Scheduler Handler
  *

cpukit/score/src/schedulersimpleenqueuefirst.c

@@ -1,6 +1,11 @@
-/*
- *  Schedule Simple Handler / Enqueue First
+/**
+ *  @file
  *
+ *  @brief Scheduler Simple Enqueue First
+ *  @ingroup ScoreScheduler
+ */
+
+/*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/score/src/smplock.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief SMP Locking Support
+ *  @ingroup RTEMS
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
@@ -67,9 +74,6 @@
   #define debug_dump_log()
 #endif
 
-/*
- * SMP spinlock simple methods
- */
 void _SMP_lock_spinlock_simple_Initialize(
   SMP_lock_spinlock_simple_Control *lock
 )
@@ -105,9 +109,6 @@ void _SMP_lock_spinlock_simple_Release(
    _ISR_Enable_on_this_core( level );
 }
 
-/*
- * SMP spinlock nested methods.
- */
 void _SMP_lock_spinlock_nested_Initialize(
   SMP_lock_spinlock_nested_Control *lock
 )

cpukit/score/src/threadqenqueuefifo.c

@@ -1,7 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief  Thread queue Enqueue FIFO
+ *  @ingroup ScoreThreadQ
+ */
+
 /*
- *  Thread Queue Handler
- *
- *
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,21 +27,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/tqdata.h>
 
-/*
- *  _Thread_queue_Enqueue_fifo
- *
- *  This routine places a blocked thread on a FIFO thread queue.
- *
- *  Input parameters:
- *    the_thread_queue - pointer to threadq
- *    the_thread       - pointer to the thread to block
- *
- *  Output parameters: NONE
- *
- *  INTERRUPT LATENCY:
- *    only case
- */
-
 Thread_blocking_operation_States _Thread_queue_Enqueue_fifo (
   Thread_queue_Control *the_thread_queue,
   Thread_Control       *the_thread,

cpukit/score/src/threadqrequeue.c

@@ -1,7 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief Thread Queue Requeue
+ *  @ingroup ScoreThreadQ
+ */
+
 /*
- *  Thread Queue Handler
- *
- *
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,21 +27,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/tqdata.h>
 
-/*
- *  _Thread_queue_Requeue
- *
- *  This routine is invoked when a thread changes priority and should be
- *  moved to a different position on the thread queue.
- *
- *  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_Requeue(
   Thread_queue_Control *the_thread_queue,
   Thread_Control       *the_thread

cpukit/score/src/threadsetpriority.c

@@ -1,6 +1,11 @@
-/*
- *  Thread Handler / Thread Set Priority
+/**
+ *  @file
  *
+ *  @brief Set Thread Priority
+ *  @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/score/src/ts64dividebyinteger.c

@@ -1,6 +1,9 @@
 /**
- * @file score/src/ts64dividebyinteger.c
-*/
+ *  @file
+ *
+ *  @brief Divide Timestamp By Integer
+ *  @ingroup SuperCore
+ */
 
 /*
  *  COPYRIGHT (c) 1989-2008.

cpukit/score/src/watchdogadjust.c

@@ -1,7 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief Watchdog Adjust
+ *  @ingroup ScoreWatchdog
+ */
+
 /*
- *  Watchdog Handler
- *
- *
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -18,20 +22,6 @@
 #include <rtems/score/isr.h>
 #include <rtems/score/watchdog.h>
 
-/*
- *  _Watchdog_Adjust
- *
- *  This routine adjusts the delta chain backward or forward in response
- *  to a time change.
- *
- *  Input parameters:
- *    header    - pointer to the delta chain to be adjusted
- *    direction - forward or backward adjustment to delta chain
- *    units     - units to adjust
- *
- *  Output parameters:
- */
-
 void _Watchdog_Adjust(
   Chain_Control               *header,
   Watchdog_Adjust_directions   direction,