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

cpukit/score/include/rtems/score/chain.h

@@ -130,10 +130,12 @@ void _Chain_Initialize(
  *  @brief Extract the specified node from a chain
  *
  *  This routine extracts @a the_node from the chain on which it resides.
- *  It disables interrupts to ensure the atomicity of the
- *  extract operation.
+ *  It disables interrupts to ensure the atomicity of the extract operation.
  *
- *  @arg the_node specifies the node to extract
+ *  @param[in] the_node is the node to be extracted
+ *
+ *  - INTERRUPT LATENCY:
+ *    + single case
  */
 void _Chain_Extract(
   Chain_Node *the_node
@@ -160,9 +162,15 @@ 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] node is the pointer to the node to be inserted
  *
  *  @note It disables interrupts to ensure the atomicity
- *  of the extract operation.
+ *  of the insert operation.
+ *
+ *  - INTERRUPT LATENCY:
+ *    + single case
  */
 void _Chain_Insert(
   Chain_Node *after_node,

cpukit/score/include/rtems/score/corebarrier.h

@@ -156,6 +156,8 @@ void _CORE_barrier_Wait(
 );
 
 /**
+ *  @brief Manually releases the barrier
+ *  
  *  This routine manually releases the barrier.  All of the threads waiting
  *  for the barrier will be readied.
  *

cpukit/score/include/rtems/score/corespinlock.h

@@ -110,9 +110,11 @@ typedef struct {
 }   CORE_spinlock_Control;
 
 /**
+ *  @brief Initialized a spinlock
+ *
  *  This routine initializes the spinlock based on the parameters passed.
  *
- *  @param[in] the_spinlock is the spinlock to initialize
+ *  @param[in] the_spinlock is the spinlock control block to initialize
  *  @param[in] the_spinlock_attributes define the behavior of this instance
  */
 void _CORE_spinlock_Initialize(

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

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

cpukit/score/include/rtems/score/rbtree.h

@@ -239,10 +239,17 @@ RBTree_Node *_RBTree_Find(
 );
 
 /**
- * @brief Find the control structure of the tree containing the given node
+ *  @brief Find the control structure of the tree containing the given node
  *
- *  This function returns a pointer to the control structure of the tree
- *  containing @a the_node, if it exists, and NULL if not.
+ *  This function returns a pointer called @a return_header to the control structure of the tree
+ *  containing @a the_node, if it exists, and @a NULL if not.
+ *
+ *  @param[in] the_node is the pointer to the rbtree node.
+ *  @param[out] return_header is the pointer to control header of rbtree.
+ *  @param[out] NULL is returned if there is no control header available.
+ *  
+ *  -INTERRUPT LATENCY:
+ *    + single case
  */
 RBTree_Control *_RBTree_Find_header(
   RBTree_Node *the_node

cpukit/score/include/rtems/score/schedulercbs.h

@@ -225,6 +225,8 @@ int _Scheduler_CBS_Create_server (
  *
  *  Detach all tasks from a server and destroy it.
  *
+ *  @param[in] server_id is the ID of the server
+ *
  *  @return status code.
  */
 int _Scheduler_CBS_Destroy_server (

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

@@ -75,6 +75,8 @@ void _Scheduler_simple_Schedule( void );
 void _Scheduler_simple_Yield( void );
 
 /**
+ *  @brief Removes a thread from the queue
+ *
  *  This routine removes @a the_thread from the scheduling decision,
  *  that is, removes it from the ready queue.  It performs
  *  any necessary scheduling operations including the selection of

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

@@ -626,7 +626,7 @@ void _Thread_Close(
 );
 
 /**
- *  This routine removes any set states for the_thread.  It performs
+ *  This routine removes any set states for @a the_thread.  It performs
  *  any necessary scheduling operations including the selection of
  *  a new heir thread.
  */
@@ -635,7 +635,7 @@ void _Thread_Ready(
 );
 
 /**
- *  This routine clears the indicated STATES for the_thread.  It performs
+ *  This routine clears the indicated STATES for @a the_thread.  It performs
  *  any necessary scheduling operations including the selection of
  *  a new heir thread.
  */
@@ -645,7 +645,7 @@ void _Thread_Clear_state(
 );
 
 /**
- *  This routine sets the indicated states for the_thread.  It performs
+ *  This routine sets the indicated states for @a the_thread.  It performs
  *  any necessary scheduling operations including the selection of
  *  a new heir thread.
  */
@@ -655,9 +655,16 @@ void _Thread_Set_state(
 );
 
 /**
- *  This routine sets the TRANSIENT state for the_thread.  It performs
+ *  @brief Sets the Transient state for a Thread
+ *
+ *  This routine sets the Transient state for @a the_thread.  It performs
  *  any necessary scheduling operations including the selection of
  *  a new heir thread.
+ *
+ *  @param[in] the_thread is the thread to preform the action upon.
+ *
+ *  - INTERRUPT LATENCY:
+ *    + single case
  */
 void _Thread_Set_transient(
   Thread_Control *the_thread
@@ -748,14 +755,19 @@ void rtems_iterate_over_all_threads(
 );
 
 /**
+ *  @brief Maps THread Id to a TCB Pointer
+ *  
  *  This function maps thread IDs to thread control
  *  blocks.  If ID corresponds to a local thread, then it
  *  returns the_thread control pointer which maps to ID
- *  and location is set to OBJECTS_LOCAL.  If the thread ID is
+ *  and @a location is set to OBJECTS_LOCAL.  If the thread ID is
  *  global and resides on a remote node, then location is set
  *  to OBJECTS_REMOTE, and the_thread is undefined.
  *  Otherwise, location is set to OBJECTS_ERROR and
  *  the_thread is undefined.
+ *  
+ *  @param[in] id is the id of the thread.
+ *  @param[in] location is the location of the block.
  *
  *  @note  The performance of many RTEMS services depends upon
  *         the quick execution of the "good object" path in this

cpukit/score/include/rtems/score/tod.h

@@ -266,7 +266,7 @@ void _TOD_Tickle_ticks( void );
 #define TOD_MILLISECONDS_TO_MICROSECONDS(_ms) ((uint32_t)(_ms) * 1000L)
 
 /**
- *  @brief TOD_MICROSECONDS_TO_TICKS
+ *  @brief Converts microseconds to ticks
  *
  *  This routine converts an interval expressed in microseconds to ticks.
  *

cpukit/score/src/chainextract.c

@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Extracts a Node from a Chain
+ *
+ * @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_Extract
- *
- *  This kernel routine deletes the given node from a chain.
- *
- *  Input parameters:
- *    node - pointer to node in chain to be deleted
- *
- *  Output parameters:  NONE
- *
- *  INTERRUPT LATENCY:
- *    only case
- */
-
 void _Chain_Extract(
   Chain_Node *node
 )

cpukit/score/src/chaininsert.c

@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Extracts a node from a given chain
+ *
+ * @ingroup ScoreChain
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).

cpukit/score/src/corebarrierrelease.c

@@ -1,10 +1,12 @@
+/**
+ * @file
+ *
+ * @brief Manually releases the Barrier
+ *
+ * @ingroup ScoreBarrier
+ */
+
 /*
- *  SuperCore Barrier Handler
- *
- *  DESCRIPTION:
- *
- *  This package is part of the implementation of the SuperCore Barrier Handler.
- *
  *  COPYRIGHT (c) 1989-2006.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,22 +26,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/threadq.h>
 
-/*
- *  _CORE_barrier_Release
- *
- *  Input parameters:
- *    the_barrier            - the barrier to be flushed
- *    id                     - id of the object for a remote unblock
- *    api_barrier_mp_support - api dependent MP support actions
- *
- *  Output parameters:
- *    CORE_BARRIER_STATUS_SUCCESSFUL - if successful
- *    core error code                - if unsuccessful
- *
- *  Output parameters:
- *    returns number of threads unblocked
- */
-
 uint32_t _CORE_barrier_Release(
   CORE_barrier_Control                *the_barrier,
 #if defined(RTEMS_MULTIPROCESSING)

cpukit/score/src/coresemseize.c

@@ -1,12 +1,12 @@
+/**
+ * @file
+ *
+ * @brief Core Semaphore Seize
+ *
+ * @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-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -27,21 +27,6 @@
 #include <rtems/score/threadq.h>
 
 #if defined(RTEMS_SCORE_CORESEM_ENABLE_SEIZE_BODY)
-/*
- *  This routine attempts to allocate a core semaphore to the calling thread.
- *
- *  Input parameters:
- *    the_semaphore - pointer to semaphore control block
- *    id            - id of object to wait on
- *    wait          - true if wait is allowed, false otherwise
- *    timeout       - number of ticks to wait (0 means forever)
- *
- *  Output parameters:  NONE
- *
- *  INTERRUPT LATENCY:
- *    available
- *    wait
- */
 
 void _CORE_semaphore_Seize(
   CORE_semaphore_Control *the_semaphore,

cpukit/score/src/corespinlock.c

@@ -1,10 +1,12 @@
+/**
+ * @file
+ *
+ * @brief Initialize a Spinlock
+ *
+ * @ingroup ScoreSpinlock
+ */
+
 /*
- *  SuperCore Spinlock Handler
- *
- *  DESCRIPTION:
- *
- *  This package is part of the implementation of the SuperCore Spinlock Handler.
- *
  *  COPYRIGHT (c) 1989-2006.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,19 +25,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/threadq.h>
 
-/*
- *  _CORE_spinlock_Initialize
- *
- *  This function initialize a spinlock and sets the initial value based
- *  on the given count.
- *
- *  Input parameters:
- *    the_spinlock            - the spinlock control block to initialize
- *    the_spinlock_attributes - the attributes specified at create time
- *
- *  Output parameters:  NONE
- */
-
 void _CORE_spinlock_Initialize(
   CORE_spinlock_Control       *the_spinlock,
   CORE_spinlock_Attributes    *the_spinlock_attributes

cpukit/score/src/coretodmsecstoticks.c

@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Convert Microseconds to Ticks
+ *
+ * @ingroup ScoreTODConstants
+ */
+
 /*  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/score/src/objectgetnameasstring.c

@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Extracts a Node from a Chain
+ *
+ * @ingroup Score
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).

cpukit/score/src/rbtreefindheader.c

@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Finds the Header of a Tree if it Exists
+ *
+ * @ingroup ScoreRBTree
+ */
+
 /*
  *  Copyright (c) 2010 Gedare Bloom.
  *
@@ -15,24 +23,6 @@
 #include <rtems/score/rbtree.h>
 #include <rtems/score/isr.h>
 
-/*
- *  _RBTree_Find_header
- *
- *  This kernel routine returns a pointer to the rbtree header of the tree
- *  containing the given node.
- *
- *  Input parameters:
- *    the_node - pointer to rbtree node
- *
- *  Output parameters:
- *    return_header - pointer to control header of rbtree
- *    NULL   - if there is no control header available (the node is not part
- *    of a tree)
- *
- *  INTERRUPT LATENCY:
- *    only case
- */
-
 RBTree_Control *_RBTree_Find_header(
   RBTree_Node *the_node
 )

cpukit/score/src/schedulercbsdestroyserver.c

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

cpukit/score/src/schedulercbsdetachthread.c

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

cpukit/score/src/schedulercbsreleasejob.c

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

cpukit/score/src/scheduleredfprioritycompare.c

@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Compares Priorities of Threads
+ *
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  Copyright (C) 2011 Petr Benes.
  *  Copyright (C) 2011 On-Line Applications Research Corporation (OAR).

cpukit/score/src/schedulerprioritytick.c

@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Priority Scheduler At Tick Handler
+ *
+ * @ingroup ScoreScheduler
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).

cpukit/score/src/schedulersimpleblock.c

@@ -1,6 +1,12 @@
-/*
- *  Scheduler Simple Handler / Block
+/**
+ * @file
  *
+ * @brief Simple Scheduler Block a Thread
+ *
+ * @ingroup ScoreScheduler
+ */
+
+/*
  *  COPYRIGHT (c) 2011.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/score/src/threadget.c

@@ -1,6 +1,12 @@
-/*
- *  Thread Handler - Object Id to Thread Pointer
+/**
+ * @file
  *
+ * @brief Maps Thread IDs to TCB Pointer
+ *
+ * @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -25,23 +31,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/threadq.h>
 
-
-/**
- *  This function maps thread IDs to thread control
- *  blocks.  If ID corresponds to a local thread, then it
- *  returns the_thread control pointer which maps to ID
- *  and location is set to OBJECTS_LOCAL.  If the thread ID is
- *  global and resides on a remote node, then location is set
- *  to OBJECTS_REMOTE, and the_thread is undefined.
- *  Otherwise, location is set to OBJECTS_ERROR and
- *  the_thread is undefined.
- *
- *  @note  The performance of many RTEMS services depends upon
- *         the quick execution of the "good object" path in this
- *         routine.  If there is a possibility of saving a few
- *         cycles off the execution time, this routine is worth
- *         further optimization attention.
- */
 Thread_Control *_Thread_Get (
   Objects_Id         id,
   Objects_Locations *location

cpukit/score/src/threadqdequeue.c

@@ -1,7 +1,12 @@
+/**
+ * @file
+ *
+ * @brief Thread Queue Dequeue
+ *
+ * @ingroup ScoreThreadQ
+ */
+
 /*
- *  Thread Queue Handler
- *
- *
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,23 +28,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/tqdata.h>
 
-/*
- *  _Thread_queue_Dequeue
- *
- *  This routine removes a thread from the specified threadq.  If the
- *  threadq discipline is FIFO, it unblocks a thread, and cancels its
- *  timeout timer.  Priority discipline is processed elsewhere.
- *
- *  Input parameters:
- *    the_thread_queue - pointer to threadq
- *
- *  Output parameters:
- *    returns - thread dequeued or NULL
- *
- *  INTERRUPT LATENCY:
- *    check sync
- */
-
 Thread_Control *_Thread_queue_Dequeue(
   Thread_queue_Control *the_thread_queue
 )

cpukit/score/src/threadqextractfifo.c

@@ -1,7 +1,12 @@
+/**
+ * @file
+ *
+ * @brief Removes a Thread from a Thread  Queue
+ *
+ * @ingroup ScoreThreadQ
+ */
+
 /*
- *  Thread Queue Handler
- *
- *
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,22 +28,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/tqdata.h>
 
-/*
- *  _Thread_queue_Extract_fifo
- *
- *  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 the thread to block
- *
- *  Output parameters: NONE
- *
- *  INTERRUPT LATENCY:
- *    EXTRACT_FIFO
- */
-
 void _Thread_queue_Extract_fifo(
   Thread_queue_Control *the_thread_queue __attribute__((unused)),
   Thread_Control       *the_thread

cpukit/score/src/threadsettransient.c

@@ -1,6 +1,12 @@
-/*
- *  Thread Handler / Thread Set Transient
+/**
+ * @file
  *
+ * @brief Sets the Transient State for a Thread
+ *
+ * @ingroup ScoreThread
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,10 +34,6 @@
 #include <rtems/score/threadq.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  INTERRUPT LATENCY:
- *    only case
- */
 void _Thread_Set_transient(
   Thread_Control *the_thread
 )

cpukit/score/src/timespecdividebyinteger.c

@@ -1,5 +1,9 @@
 /**
- *  @file  score/src/timespecdividebyinteger.c
+ * @file
+ *
+ * @brief Divide Timespec By Integer
+ *
+ * @ingroup Timespec
  */
 
 /*

cpukit/score/src/ts64settozero.c

@@ -1,6 +1,10 @@
 /**
- * @file score/src/ts64settozero.c
-*/
+ * @file
+ *
+ * @brief Zero a Timestamp64 Instance
+ *
+ * @ingroup SuperCore
+ */
 
 /*
  *  COPYRIGHT (c) 1989-2008.