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, 53 insertions, 28 deletions

diff --git a/cpukit/score/include/rtems/score/priority.h b/cpukit/score/include/rtems/score/priority.h
index 58b70add1b..bfe43e282d 100644
--- a/cpukit/score/include/rtems/score/priority.h
+++ b/cpukit/score/include/rtems/score/priority.h
@@ -7,7 +7,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
@@ -23,7 +23,16 @@
 /**
  *  @defgroup ScorePriority Priority Handler
  *
- *  This group contains functionality which XXX
+ *  This handler encapsulates functionality which is used to manage
+ *  thread priorities.  At the SuperCore level 256 priority levels
+ *  are supported with lower numbers representing logically more important
+ *  threads.  The priority level 0 is reserved for internal RTEMS use. 
+ *  Typically it is assigned to threads which defer internal RTEMS 
+ *  actions from an interrupt to thread level to improve interrupt response.
+ *  Priority level 255 is assigned to the IDLE thread and really should not
+ *  be used by application threads.  The default IDLE thread implementation
+ *  is an infinite "branch to self" loop which never yields to other threads
+ *  at the same priority.
  */
 /**@{*/
 
@@ -31,43 +40,48 @@
 extern "C" {
 #endif
 
-/*
+/**
  *  The following type defines the control block used to manage
  *  thread priorities.
  *
  *  @note Priority 0 is reserved for internal threads only.
  */
-
 typedef uint32_t   Priority_Control;
 
-#define PRIORITY_MINIMUM      0         /* highest thread priority */
-#define PRIORITY_MAXIMUM      255       /* lowest thread priority */
+/** This defines the highest (most important) thread priority. */
+#define PRIORITY_MINIMUM      0
+/** This defines the lowest (least important) thread priority. */
+#define PRIORITY_MAXIMUM      255
 
-/*
+/**
  *  The following record defines the information associated with
  *  each thread to manage its interaction with the priority bit maps.
  */
-
 typedef struct {
-  Priority_Bit_map_control *minor;        /* addr of minor bit map slot */
-  Priority_Bit_map_control  ready_major;  /* priority bit map ready mask */
-  Priority_Bit_map_control  ready_minor;  /* priority bit map ready mask */
-  Priority_Bit_map_control  block_major;  /* priority bit map block mask */
-  Priority_Bit_map_control  block_minor;  /* priority bit map block mask */
+  /** This is the address of minor bit map slot. */
+  Priority_Bit_map_control *minor;
+  /** This is the priority bit map ready mask. */
+  Priority_Bit_map_control  ready_major;
+  /** This is the priority bit map ready mask. */
+  Priority_Bit_map_control  ready_minor;
+  /** This is the priority bit map block mask. */
+  Priority_Bit_map_control  block_major;
+  /** This is the priority bit map block mask. */
+  Priority_Bit_map_control  block_minor;
 }   Priority_Information;
 
-/*
- *  The following data items are the priority bit map.
- *  Each of the sixteen bits used in the _Priority_Major_bit_map is
- *  associated with one of the sixteen entries in the _Priority_Bit_map.
- *  Each bit in the _Priority_Bit_map indicates whether or not there are
+/**
+ *  Each sixteen bit entry in this array is associated with one of
+ *  the sixteen entries in the Priority Bit map.
+ */
+SCORE_EXTERN volatile Priority_Bit_map_control _Priority_Major_bit_map;
+
+/** Each bit in the Priority Bitmap indicates whether or not there are
  *  threads ready at a particular priority.  The mapping of
  *  individual priority levels to particular bits is processor
  *  dependent as is the value of each bit used to indicate that
  *  threads are ready at that priority.
  */
-
-SCORE_EXTERN volatile Priority_Bit_map_control _Priority_Major_bit_map;
 SCORE_EXTERN Priority_Bit_map_control
                _Priority_Bit_map[16] CPU_STRUCTURE_ALIGNMENT;
 
@@ -76,22 +90,33 @@ SCORE_EXTERN Priority_Bit_map_control
  *
  */
 
-/*
- *  Priority Bitfield Manipulation Routines
+#if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE )
+/**
+ *  This method returns the priority bit mask for the specified major
+ *  or minor bit number.
  *
- *  @note
+ *  @param[in] _bit_number is the bit number for which we need a mask
  *
- *  These may simply be pass throughs to CPU dependent routines.
+ *  @return the priority bit mask
+ *
+ *  @note This may simply be a pass through to a CPU dependent implementation.
  */
-
-#if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE )
-
 #define _Priority_Mask( _bit_number ) \
   _CPU_Priority_Mask( _bit_number )
+#endif
 
+#if ( CPU_USE_GENERIC_BITFIELD_CODE == FALSE )
+/**
+ *  This method returns the bit index position for the specified priority.
+ *
+ *  @param[in] _priority is the priority for which we need the index.
+ *
+ *  @return This method returns the array index into the priority bit map.
+ *
+ *  @note This may simply be a pass through to a CPU dependent implementation.
+ */
 #define _Priority_Bits_index( _priority ) \
   _CPU_Priority_bits_index( _priority )
-
 #endif
 
 #ifndef __RTEMS_APPLICATION__