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

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

@@ -259,9 +259,13 @@ int _Scheduler_CBS_Get_remaining_budget (
 );
 
 /**
- *  @brief _Scheduler_CBS_Get_execution_time
+ *  @brief Get relative time info
  *
- *  Retrieve time info relative to the current server.
+ *  Retrieve time info relative to @a server_id. The server status code is returned.
+ *
+ *  @param[in] server_id is the server to get the status code from.
+ *  @param[in] exec_time is the execution time.
+ *  @param[in] abs_time is not apparently used. 
  *
  *  @return status code.
  */

cpukit/score/include/rtems/score/scheduleredf.h

@@ -105,7 +105,7 @@ extern RBTree_Control _Scheduler_EDF_Ready_queue;
 void _Scheduler_EDF_Initialize( void );
 
 /**
- *  @brief Scheduler EDF Block
+ *  @brief Removes Thread from Ready Queue
  *
  *  This routine removes @a the_thread from the scheduling decision,
  *  that is, removes it from the ready queue.  It performs
@@ -139,7 +139,7 @@ void *_Scheduler_EDF_Allocate(
 );
 
 /**
- *  @brief Scheduler EDF Free
+ *  @brief Frees EDF information of a thread 
  *
  *  This routine frees the EDF specific information of @a the_thread.
  *

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

@@ -175,6 +175,8 @@ void _Scheduler_priority_Enqueue_first(
 );
 
 /**
+ *  @brief Removes a specific thread from scheduler  
+ *
  *  This routine removes a specific thread from the scheduler's set
  *  of ready threads.
  *

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

@@ -50,7 +50,9 @@ extern "C" {
   }
 
 /**
- * This routine initializes the simple scheduler.
+ *  @brief Initializes simple scheduler
+ *
+ *  This routine initializes the simple scheduler.
  */
 void _Scheduler_simple_Initialize( void );
 
@@ -100,6 +102,8 @@ void _Scheduler_simple_Unblock(
 );
 
 /**
+ *  @brief Removes a thread from a simple queue
+ *
  *  This routine removes a specific thread from the specified
  *  simple-based ready queue.
  *
@@ -110,9 +114,11 @@ void _Scheduler_simple_Extract(
 );
 
 /**
+ *  @brief Puts thread onto the ready queue
+ *
  *  This routine puts @a the_thread on to the ready queue.
  *
- *  @param[in] the_thread is the thread to be blocked
+ *  @param[in] the_thread is the thread to be enqueued
  */
 void _Scheduler_simple_Enqueue(
   Thread_Control *the_thread
@@ -131,6 +137,8 @@ void _Scheduler_simple_Enqueue_first(
 );
 
 /**
+ *  @brief Returns empty placeholder for scheduler
+ *
  *  This routine is a place holder for any memeory allocation needed
  *  by the scheduler.  For the simple scheduler the routine is an empty
  *  place holder.
@@ -146,9 +154,10 @@ void *_Scheduler_simple_Allocate(
 );
 
 /**
- * This routine does nothing, and is used as a stub for Schedule update
+ *  @breif Stub for schedule update
  *
- * The overhead of a function call will still be imposed.
+ *  This routine does nothing, and is used as a stub for Schedule update
+ *  The overhead of a function call will still be imposed.
  *
  *  @param[in] the_thread is the thread to be blocked
  */
@@ -157,9 +166,10 @@ void _Scheduler_simple_Update(
 );
 
 /**
- * This routine does nothing, and is used as a stub for Schedule free
+ *  @brief Stub for schedule free 
  *
- * The overhead of a function call will still be imposed.
+ *  This routine does nothing, and is used as a stub for Schedule free
+ *  The overhead of a function call will still be imposed.
  *
  *  @param[in] the_thread is the thread to be blocked
  */

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

@@ -546,9 +546,9 @@ void _Thread_Start_multitasking( void );
  *  ALTERNATE ENTRY POINTS:
  *    void _Thread_Enable_dispatch();
  *
- *  INTERRUPT LATENCY:
- *    dispatch thread
- *    no dispatch thread
+ *  - INTERRUPT LATENCY:
+ *    + dispatch thread
+ *    + no dispatch thread
  */
 void _Thread_Dispatch( void );
 
@@ -739,9 +739,15 @@ void _Thread_Delay_ended(
 );
 
 /**
- *  This routine changes the current priority of the_thread to
- *  new_priority.  It performs any necessary scheduling operations
+ *  @brief Changes the priority of a thread
+ *  
+ *  This routine changes the current priority of @a the_thread to
+ *  @a new_priority.  It performs any necessary scheduling operations
  *  including the selection of a new heir thread.
+ *
+ *  @param[in] the_thread is the thread to change
+ *  @param[in] new_priority is the priority to set @a the_thread to
+ *  @param[in] prepend_it is a switch to prepend the thread
  */
 void _Thread_Change_priority (
   Thread_Control   *the_thread,

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

@@ -119,10 +119,13 @@ void _Thread_queue_Requeue(
 );
 
 /**
- *  @brief Thread Queue Extract
+ *  @brief Extracts Thread from Thread Queue
  *
- *  This routine removes the_thread from the_thread_queue
+ *  This routine removes @a the_thread from @a the_thread_queue
  *  and cancels any timeouts associated with this blocking.
+ * 
+ *  @param[in] the_thread_queue is the pointer to the ThreadQ header
+ *  @param[in] the_thread is the pointer to a thread control block that is to be removed
  */
 void _Thread_queue_Extract(
   Thread_queue_Control *the_thread_queue,
@@ -237,11 +240,14 @@ void _Thread_queue_Extract_priority_helper(
 
 
 /**
- *  @brief Thread Queue First priority
+ *  @brief Returns highest priority thread on the_thread_queue
  *
  *  This function returns a pointer to the "first" thread
- *  on the_thread_queue.  The "first" thread is the highest
- *  priority thread waiting on the_thread_queue.
+ *  on @a the_thread_queue.  The "first" thread is the highest
+ *  priority thread waiting on @a the_thread_queue.
+ *
+ *  @param[in] the_thread_queue is the pointer to the thread queue
+ *  @return first thread or NULL
  */
 Thread_Control *_Thread_queue_First_priority(
   Thread_queue_Control *the_thread_queue

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

@@ -173,10 +173,12 @@ SCORE_EXTERN TOD_Control _TOD;
 void _TOD_Handler_initialization(void);
 
 /**
- *  @brief Sets the time of day according to @a tod_as_timestamp.
+ *  @brief Sets the time of day from timestamp
  *
  *  The @a tod_as_timestamp timestamp represents the time since UNIX epoch.
  *  The watchdog seconds chain will be adjusted.
+ *
+ *  @param[in] tod_as_timestamp is the constant of the time of day as a timestamp
  */
 void _TOD_Set_with_timestamp(
   const Timestamp_Control *tod_as_timestamp
@@ -251,6 +253,8 @@ void _TOD_Get_uptime_as_timespec(
 );
 
 /**
+ *  @brief Increments time of day at each clock tick
+ *
  *  This routine increments the ticks field of the current time of
  *  day at each clock tick.
  */

cpukit/score/include/rtems/score/userextimpl.h

@@ -143,7 +143,7 @@ void _User_extensions_Fatal_visitor(
  * @brief Iterates through all user extensions and calls the visitor for each.
  *
  * @param[in, out] arg The argument passed to the visitor.
- * @param[in] visitor The visitor for each extension.
+ * @param[in] visitor is the visitor for each extension.
  */
 void _User_extensions_Iterate(
   void                    *arg,

cpukit/score/include/rtems/score/wkspace.h

@@ -102,10 +102,10 @@ void *_Workspace_Allocate_or_fatal_error(
 );
 
 /**
- * @brief Duplicates the @a string with memory from the Workspace.
+ * @brief Duplicates String with Memory from the Workspace
  *
- * @param[in] string Pointer to zero terminated string.
- * @param[in] len Length of the string (equal to strlen(string)).
+ * @param[in] string is the pointer to a zero terminated string.
+ * @param[in] len is the length of the string (equal to strlen(string)).
  *
  * @return NULL Not enough memory.
  * @return other Duplicated string.

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,

cpukit/score/src/coremsgsubmit.c

@@ -1,12 +1,12 @@
+/**
+ * @file
+ *
+ * @brief CORE Message Queue Submit
+ *
+ * @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).
  *
@@ -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,

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.

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;

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).
  *

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).

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).

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).

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).
  *

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;

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).
  *

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).
  *

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).
  *

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).
  *

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 )
 {

cpukit/score/src/threadqextract.c

@@ -1,7 +1,12 @@
+/**
+ * @file
+ *
+ * @brief Extracts Thread from Thread Queue
+ *
+ * @ingroup ScoreThreadQ
+ */
+
 /*
- *  Thread Queue Handler
- *
- *
  *  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

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
 )

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.
  *

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.
  *

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.
  *