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, 102 insertions, 33 deletions

diff --git a/cpukit/score/inline/rtems/score/heap.inl b/cpukit/score/inline/rtems/score/heap.inl
index 645551e153..d34ce759ee 100644
--- a/cpukit/score/inline/rtems/score/heap.inl
+++ b/cpukit/score/inline/rtems/score/heap.inl
@@ -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
@@ -28,8 +28,12 @@
 
 /**
  *  This function returns the head of the specified heap.
+ *
+ *  @param[in] the_heap points to the heap being operated upon
+ *
+ *  @return This method returns a pointer to the dummy head of the free
+ *          block list.
  */
-
 RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Head (
   Heap_Control *the_heap
 )
@@ -39,8 +43,12 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Head (
 
 /**
  *  This function returns the tail of the specified heap.
+ *
+ *  @param[in] the_heap points to the heap being operated upon
+ *
+ *  @return This method returns a pointer to the dummy tail of the heap
+ *          free list.
  */
-
 RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Tail (
   Heap_Control *the_heap
 )
@@ -50,8 +58,11 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Tail (
 
 /**
  *  Return the first free block of the specified heap.
+ *
+ *  @param[in] the_heap points to the heap being operated upon
+ *
+ *  @return This method returns a pointer to the first free block.
  */
-
 RTEMS_INLINE_ROUTINE Heap_Block *_Heap_First (
   Heap_Control *the_heap
 )
@@ -59,15 +70,13 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_First (
   return _Heap_Head(the_heap)->next;
 }
 
-/*PAGE
- *
- *  _Heap_Last
+/**
+ *  Return the last free block of the specified heap.
  *
- *  DESCRIPTION:
+ *  @param[in] the_heap points to the heap being operated upon
  *
- *  Return the last free block of the specified heap.
+ *  @return This method returns a pointer to the last block on the free list.
  */
-
 RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Last (
   Heap_Control *the_heap
 )
@@ -75,15 +84,12 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Last (
   return _Heap_Tail(the_heap)->prev;
 }
 
-/*PAGE
- *
- *  _Heap_Block_remove
- *
- *  DESCRIPTION:
- *
+/**
  *  This function removes 'the_block' from doubly-linked list.
+ *
+ *  @param[in] the_block is the block to remove from the heap used block
+ *             list.
  */
-
 RTEMS_INLINE_ROUTINE void _Heap_Block_remove (
   Heap_Block *the_block
 )
@@ -98,6 +104,14 @@ RTEMS_INLINE_ROUTINE void _Heap_Block_remove (
 
 /**
  *  This function replaces @a old_block by @a new_block in doubly-linked list.
+ *  When a block is allocated, the memory is allocated from the low memory 
+ *  address range of the block.  This means that the upper address range of 
+ *  the memory block must be added to the free block list in place of the
+ *  lower address portion being allocated.  This method is also used as part
+ *  of resizing a block.
+ *
+ *  @param[in] old_block is the block which is currently on the list.
+ *  @param[in] new_block is the new block which will replace it on the list.
  */
 
 RTEMS_INLINE_ROUTINE void _Heap_Block_replace (
@@ -117,7 +131,10 @@ RTEMS_INLINE_ROUTINE void _Heap_Block_replace (
 
 /**
  *  This function inserts @a the_block after @a prev_block
- *  in doubly-linked list.
+ *  in the doubly-linked free block list.
+ *
+ *  @param[in] prev_block is the previous block in the free list.
+ *  @param[in] the_block is the block being freed.
  */
 RTEMS_INLINE_ROUTINE void _Heap_Block_insert_after (
   Heap_Block *prev_block,
@@ -135,8 +152,13 @@ RTEMS_INLINE_ROUTINE void _Heap_Block_insert_after (
 
 /**
  *  Return TRUE if @a value is a multiple of @a alignment,  FALSE otherwise
+ *
+ *  @param[in] value is the address to verify alignment of.
+ *  @param[in] alignment is the alignment factor to verify.
+ *
+ *  @return This method returns TRUE if the address is aligned and false
+ *          otherwise.
  */
-
 RTEMS_INLINE_ROUTINE boolean _Heap_Is_aligned (
   uint32_t  value,
   uint32_t  alignment
@@ -147,8 +169,12 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_aligned (
 
 /**
  *  Align @a *value up to the nearest multiple of @a alignment.
+ *
+ *  @param[in] value is a pointer to be aligned.
+ *  @param[in] alignment is the alignment value.
+ *
+ *  @return Upon return, @a value will contain the aligned result.
  */
-
 RTEMS_INLINE_ROUTINE void _Heap_Align_up (
   uint32_t *value,
   uint32_t  alignment
@@ -162,8 +188,12 @@ RTEMS_INLINE_ROUTINE void _Heap_Align_up (
 
 /**
  *  Align @a *value down to the nearest multiple of @a alignment.
+ *
+ *  @param[in] value is a pointer to be aligned.
+ *  @param[in] alignment is the alignment value.
+ *
+ *  @return Upon return, @a value will contain the aligned result.
  */
-
 RTEMS_INLINE_ROUTINE void _Heap_Align_down (
   uint32_t *value,
   uint32_t  alignment
@@ -175,11 +205,16 @@ RTEMS_INLINE_ROUTINE void _Heap_Align_down (
 
 /**
  *  Return TRUE if @a ptr is aligned at @a alignment boundary,
- *  FALSE otherwise
+ *  FALSE otherwise.
+ *
+ *  @param[in] ptr is the pointer to verify alignment of.
+ *  @param[in] alignment is the alignment factor.
+ *
+ *  @return This method returns TRUE if @a ptr is aligned at @a alignment
+ *          boundary, and FALSE otherwise.
  */
-
 RTEMS_INLINE_ROUTINE boolean _Heap_Is_aligned_ptr (
-  void *ptr,
+  void      *ptr,
   uint32_t  alignment
 )
 {
@@ -188,8 +223,12 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_aligned_ptr (
 
 /**
  *  Align @a *value up to the nearest multiple of @a alignment.
+ *
+ *  @param[in] value is a pointer to be aligned.
+ *  @param[in] alignment is the alignment value.
+ *
+ *  @return Upon return, @a value will contain the aligned result.
  */
-
 RTEMS_INLINE_ROUTINE void _Heap_Align_up_uptr (
   _H_uptr_t *value,
   uint32_t  alignment
@@ -203,8 +242,12 @@ RTEMS_INLINE_ROUTINE void _Heap_Align_up_uptr (
 
 /**
  *  Align @a *value down to the nearest multiple of @a alignment.
+ *
+ *  @param[in] value is a pointer to be aligned.
+ *  @param[in] alignment is the alignment value.
+ *
+ *  @return Upon return, @a value will contain the aligned result.
  */
-
 RTEMS_INLINE_ROUTINE void _Heap_Align_down_uptr (
   _H_uptr_t *value,
   uint32_t  alignment
@@ -217,10 +260,14 @@ RTEMS_INLINE_ROUTINE void _Heap_Align_down_uptr (
 /**
  *  This function calculates and returns a block's location (address)
  *  in the heap based upon a base address @a base and an @a offset.
+ *
+ *  @param[in] base is the base address of the memory area.
+ *  @param[in] offset is the byte offset into @a base.
+ *
+ *  @return This method returns a pointer to the block's address.
  */
-
 RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Block_at(
-  void       *base,
+  void     *base,
   uint32_t  offset
 )
 {
@@ -230,8 +277,12 @@ RTEMS_INLINE_ROUTINE Heap_Block *_Heap_Block_at(
 /**
  *  This function returns the starting address of the portion of @a the_block
  *  which the user may access.
+ *
+ *  @param[in] the_block is the heap block to find the user area of.
+ *
+ *  @return This method returns a pointer to the start of the user area in
+ *          the block.
  */
-
 RTEMS_INLINE_ROUTINE void *_Heap_User_area (
   Heap_Block *the_block
 )
@@ -242,8 +293,14 @@ RTEMS_INLINE_ROUTINE void *_Heap_User_area (
 /**
  *  Fill @a *the_block with the address of the beginning of the block given
  *  pointer to the user accessible area @a base.
+ *
+ *  @param[in] the_heap points to the heap being operated upon
+ *  @param[in] base points to the user area in the block.
+ *  @param[in] the_block will be the address of the heap block.
+ *
+ *  @return This method returns a pointer to the heap block based upon the
+ *               given heap and user pointer.
  */
-
 RTEMS_INLINE_ROUTINE void _Heap_Start_of_block (
   Heap_Control  *the_heap,
   void          *base,
@@ -262,8 +319,12 @@ RTEMS_INLINE_ROUTINE void _Heap_Start_of_block (
 /**
  *  This function returns TRUE if the previous block of @a the_block
  *  is in use, and FALSE otherwise.
+ *
+ *  @param[in] the_block is the block to operate upon.
+ *
+ *  @return This method returns TRUE if the previous block is used and FALSE
+ *          if the previous block is free.
  */
-
 RTEMS_INLINE_ROUTINE boolean _Heap_Is_prev_used (
   Heap_Block *the_block
 )
@@ -273,8 +334,11 @@ RTEMS_INLINE_ROUTINE boolean _Heap_Is_prev_used (
 
 /**
  *  This function returns the size of @a the_block in bytes.
+ *
+ *  @param[in] the_block is the block to operate upon.
+ *
+ *  @return This method returns the size of the specified heap block in bytes.
  */
-
 RTEMS_INLINE_ROUTINE uint32_t _Heap_Block_size (
   Heap_Block *the_block
 )
@@ -285,8 +349,13 @@ RTEMS_INLINE_ROUTINE uint32_t _Heap_Block_size (
 /**
  *  This function returns TRUE if @a the_block is within the memory area
  *  managed by @a the_heap, and FALSE otherwise.
+ *
+ *  @param[in] the_heap points to the heap being operated upon
+ *  @param[in] the_block is the block address to check.
+ *
+ *  @return This method returns TRUE if @a the_block appears to have been
+ *          allocated from @a the_heap, and FALSE otherwise.
  */
-
 RTEMS_INLINE_ROUTINE boolean _Heap_Is_block_in (
   Heap_Control *the_heap,
   Heap_Block   *the_block