2006-01-16 Joel Sherrill <joel@OARcorp.com>

	Large patch to improve Doxygen output.  As a side-effect, grammar and
	spelling errors were corrected, spacing errors were address, and some
	variable names were improved.
	* libmisc/monitor/mon-object.c, libmisc/monitor/monitor.h:
	Account for changing OBJECTS_NO_CLASS to OBJECTS_CLASSIC_NO_CLASS.
	* score/Doxyfile: Set output directory.  Predefine some macro values.
	Turn on graphical output.
	* score/include/rtems/debug.h, score/include/rtems/seterr.h,
	score/include/rtems/system.h, score/include/rtems/score/address.h,
	score/include/rtems/score/apiext.h,
	score/include/rtems/score/apimutex.h,
	score/include/rtems/score/bitfield.h,
	score/include/rtems/score/chain.h,
	score/include/rtems/score/context.h,
	score/include/rtems/score/coremsg.h,
	score/include/rtems/score/coremutex.h,
	score/include/rtems/score/coresem.h,
	score/include/rtems/score/heap.h, score/include/rtems/score/interr.h,
	score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h,
	score/include/rtems/score/mppkt.h,
	score/include/rtems/score/object.h,
	score/include/rtems/score/objectmp.h,
	score/include/rtems/score/priority.h,
	score/include/rtems/score/stack.h,
	score/include/rtems/score/states.h,
	score/include/rtems/score/sysstate.h,
	score/include/rtems/score/thread.h,
	score/include/rtems/score/threadmp.h,
	score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h,
	score/include/rtems/score/tqdata.h,
	score/include/rtems/score/userext.h,
	score/include/rtems/score/watchdog.h,
	score/include/rtems/score/wkspace.h,
	score/inline/rtems/score/address.inl,
	score/inline/rtems/score/chain.inl,
	score/inline/rtems/score/coremutex.inl,
	score/inline/rtems/score/coresem.inl,
	score/inline/rtems/score/heap.inl,
	score/inline/rtems/score/object.inl,
	score/inline/rtems/score/stack.inl,
	score/inline/rtems/score/thread.inl,
	score/inline/rtems/score/tqdata.inl, score/macros/README,
	score/src/heap.c, score/src/threadmp.c, score/src/threadready.c,
	score/src/threadstartmultitasking.c: Improve generated Doxygen
	output. Fix spelling and grammar errors in comments. Correct names of
	some variables and propagate changes.

1 files changed, 111 insertions, 40 deletions

diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h
index 02bf0cbd86..7fbae11397 100644
--- a/cpukit/score/include/rtems/score/thread.h
+++ b/cpukit/score/include/rtems/score/thread.h
@@ -6,7 +6,7 @@
  */
 
 /*
- *  COPYRIGHT (c) 1989-2004.
+ *  COPYRIGHT (c) 1989-2006.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be
@@ -22,7 +22,8 @@
 /**
  *  @defgroup ScoreThread Thread Handler
  *
- *  This group contains functionality which XXX
+ *  This handler encapsulates functionality related to the management of
+ *  threads.  This includes the creation, deletion, and scheduling of threads.
  */
 /**@{*/
 
@@ -67,21 +68,27 @@ typedef enum {
   THREAD_START_BOTH_NUMERIC_FIRST
 } Thread_Start_types;
 
-/**
- */
+/** This type corresponds to a very simple style thread entry point. */
 typedef Thread ( *Thread_Entry )();   /* basic type */
 
+/** This type corresponds to a thread entry point which takes a single
+ *  unsigned thirty-two bit integer as an argument.
+ */
 typedef Thread ( *Thread_Entry_numeric )( uint32_t   );
 
-/**
+/** This type corresponds to a thread entry point which takes a single
+ *  untyped pointer as an argument.
  */
 typedef Thread ( *Thread_Entry_pointer )( void * );
 
-/**
+/** This type corresponds to a thread entry point which takes a single
+ *  untyped pointer and an unsigned thirty-two bit integer as arguments.
  */
 typedef Thread ( *Thread_Entry_both_pointer_first )( void *, uint32_t   );
 
-/**
+/** This type corresponds to a thread entry point which takes a single
+ *  unsigned thirty-two bit integer and an untyped pointer and an
+ *  as arguments.
  */
 typedef Thread ( *Thread_Entry_both_numeric_first )( uint32_t  , void * );
 
@@ -99,11 +106,12 @@ typedef enum {
   THREAD_CPU_BUDGET_ALGORITHM_CALLOUT
 }  Thread_CPU_budget_algorithms;
 
-/**
+/** This type defines the Thread Control Block structure.
  */
 typedef struct Thread_Control_struct Thread_Control;
 
-/**
+/**  This defines thes the entry point for the thread specific timeslice
+ *   budget management algorithm.
  */
 typedef void (*Thread_CPU_budget_algorithm_callout )( Thread_Control * );
 
@@ -117,7 +125,7 @@ struct rtems_task_variable_tt;
  *
  *  This is the internal structure used to manager per Task Variables.
  */
-struct rtems_task_variable_tt {
+typedef struct {
   /** This field points to the next per task variable for this task. */
   struct rtems_task_variable_tt  *next;
   /** This field points to the physical memory location of this per
@@ -130,33 +138,46 @@ struct rtems_task_variable_tt {
   void                           *tval;
   /** This field points to the destructor for this per task variable. */
   void                          (*dtor)(void *);
-};
-
-/**
- */
-typedef struct rtems_task_variable_tt   rtems_task_variable_t;
+} rtems_task_variable_t;
 
 /**
  *  The following structure contains the information which defines
  *  the starting state of a thread.
  */
 typedef struct {
-  Thread_Entry         entry_point;      /* starting thread address         */
-  Thread_Start_types   prototype;        /* how task is invoked             */
-  void                *pointer_argument; /* pointer argument                */
-  uint32_t             numeric_argument; /* numeric argument                */
-                                         /* initial execution modes         */
+  /** This field is the starting address for the thread. */
+  Thread_Entry         entry_point;
+  /** This field indicatres the how task is invoked. */
+  Thread_Start_types   prototype;
+  /** This field is the pointer argument passed at thread start. */
+  void                *pointer_argument;
+  /** This field is the numeric argument passed at thread start. */
+  uint32_t             numeric_argument;
+  /*-------------- initial execution modes ----------------- */
+  /** This field indicates whether the thread was preemptible when
+    * it started.
+    */
   boolean              is_preemptible;
+  /** This field indicates the CPU budget algorith. */
   Thread_CPU_budget_algorithms          budget_algorithm;
+  /** This field is the routine to invoke when the CPU allotment is
+   *  consumed.
+   */
   Thread_CPU_budget_algorithm_callout   budget_callout;
+  /** This field is the initial ISR disable level of this thread. */
   uint32_t             isr_level;
-  Priority_Control     initial_priority; /* initial priority                */
+  /** This field is the initial priority. */
+  Priority_Control     initial_priority;
+  /** This field indicates whether the SuperCore allocated the stack. */
   boolean              core_allocated_stack;
-  Stack_Control        Initial_stack;    /* stack information               */
+  /** This field is the stack information. */
+  Stack_Control        Initial_stack;
 #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
-  void                *fp_context;       /* initial FP context area address */
+  /** This field is the initial FP context area address. */
+  void                *fp_context;
 #endif
-  void                *stack;            /* initial stack area address      */
+  /** This field is the initial stack area address. */
+  void                *stack;
 }   Thread_Start_information;
 
 /**
@@ -204,17 +225,26 @@ typedef struct {
  *        memory images for the shared part.
  */
 typedef struct {
+  /** This field is the object management structure for each proxy. */
   Objects_Control          Object;
+  /** This field is the current execution state of this proxy. */
   States_Control           current_state;
+  /** This field is the current priority state of this proxy. */
   Priority_Control         current_priority;
+  /** This field is the base priority of this proxy. */
   Priority_Control         real_priority;
+  /** This field is the number of mutexes currently held by this proxy. */
   uint32_t                 resource_count;
+  /** This field is the blocking information for this proxy. */
   Thread_Wait_information  Wait;
+  /** This field is the Watchdog used to manage proxy delays and timeouts. */
   Watchdog_Control         Timer;
 #if defined(RTEMS_MULTIPROCESSING)
+  /** This field is the received response packet in an MP system. */
   MP_packet_Prefix        *receive_packet;
 #endif
      /****************** end of common block ********************/
+  /** This field is used to manage the set of proxies in the system. */
   Chain_Node               Active;
 }   Thread_Proxy_control;
 
@@ -226,54 +256,95 @@ typedef struct {
  *        memory images for the shared part.
  */
 typedef enum {
+  /** This value is for the Classic RTEMS API. */
   THREAD_API_RTEMS,
+  /** This value is for the POSIX API. */
   THREAD_API_POSIX,
+  /** This value is for the ITRON API. */
   THREAD_API_ITRON
 }  Thread_APIs;
 
-/**
- */
+/** This macro defines the first API which has threads. */
 #define THREAD_API_FIRST THREAD_API_RTEMS
 
-/**
- */
+/** This macro defines the last API which has threads. */
 #define THREAD_API_LAST  THREAD_API_ITRON
 
 /**
+ *  This structure defines the Thread Control Block (TCB).
  */
 struct Thread_Control_struct {
-  Objects_Control                       Object;
-  States_Control                        current_state;
-  Priority_Control                      current_priority;
-  Priority_Control                      real_priority;
-  uint32_t                              resource_count;
-  Thread_Wait_information               Wait;
-  Watchdog_Control                      Timer;
+  /** This field is the object management structure for each thread. */
+  Objects_Control          Object;
+  /** This field is the current execution state of this thread. */
+  States_Control           current_state;
+  /** This field is the current priority state of this thread. */
+  Priority_Control         current_priority;
+  /** This field is the base priority of this thread. */
+  Priority_Control         real_priority;
+  /** This field is the number of mutexes currently held by this thread. */
+  uint32_t                 resource_count;
+  /** This field is the blocking information for this thread. */
+  Thread_Wait_information  Wait;
+  /** This field is the Watchdog used to manage thread delays and timeouts. */
+  Watchdog_Control         Timer;
 #if defined(RTEMS_MULTIPROCESSING)
-  MP_packet_Prefix                     *receive_packet;
+  /** This field is the received response packet in an MP system. */
+  MP_packet_Prefix        *receive_packet;
 #endif
-     /****************** end of common block ********************/
+     /*================= end of common block =================*/
+  /** This field is the number of nested suspend calls. */
   uint32_t                              suspend_count;
+  /** This field is true if the thread is offered globally */
   boolean                               is_global;
+  /** This field is is true if the post task context switch should be 
+   *  executed for this thread at the next context switch.
+   */
   boolean                               do_post_task_switch_extension;
-
+  /** This field is true if the thread is preemptible. */
   boolean                               is_preemptible;
+  /** This field is the GNAT self context pointer. */
   void                                 *rtems_ada_self;
+  /** This field is the length of the time quantum that this thread is
+   *  allowed to consume.  The algorithm used to manage limits on CPU usage
+   *  is specified by budget_algorithm.
+   */
   uint32_t                              cpu_time_budget;
+  /** This field is the algorithm used to manage this thread's time
+   *  quantum.  The algorithm may be specified as none which case,
+   *  no limit is in place.
+   */
   Thread_CPU_budget_algorithms          budget_algorithm;
+  /** This field is the method invoked with the budgeted time is consumed. */
   Thread_CPU_budget_algorithm_callout   budget_callout;
 
+  /** This field is the number of clock ticks executed by this thread
+   *  since it was created.
+   */
   uint32_t                              ticks_executed;
+  /** This field points to the Ready FIFO for this priority. */
   Chain_Control                        *ready;
+  /** This field contains precalculated priority map indices. */
   Priority_Information                  Priority_map;
+  /** This field contains information about the starting state of
+   *  this thread.
+   */
   Thread_Start_information              Start;
+  /** This field contains the context of this thread. */
   Context_Control                       Registers;
 #if ( CPU_HARDWARE_FP == TRUE ) || ( CPU_SOFTWARE_FP == TRUE )
+  /** This field points to the floating point context for this thread.
+   *  If NULL, the thread is integer only.
+   */
   void                                 *fp_context;
 #endif
+  /** This field points to the newlib reentrancy structure for this thread. */
   struct _reent                        *libc_reent;
+  /** This array contains the API extension area pointers. */
   void                                 *API_Extensions[ THREAD_API_LAST + 1 ];
+  /** This field points to the user extension pointers. */
   void                                **extensions;
+  /** This field points to the set of per task variables. */
   rtems_task_variable_t                *task_variables;
 };
 
@@ -303,7 +374,7 @@ SCORE_EXTERN Thread_Control *_Thread_Idle;
  */
 SCORE_EXTERN Context_Control _Thread_BSP_context;
 
-/***
+/**
  *  The following declares the dispatch critical section nesting
  *  counter which is used to prevent context switches at inopportune
  *  moments.
@@ -651,7 +722,7 @@ Thread _Thread_Idle_body(
 );
 #endif
 
-/**
+/**  This defines the type for a method which operates on a single thread.
  */
 typedef void (*rtems_per_thread_routine)( Thread_Control * );