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, 161 insertions, 57 deletions

diff --git a/cpukit/score/inline/rtems/score/chain.inl b/cpukit/score/inline/rtems/score/chain.inl
index 3a6f10e2e6..d394ec93e1 100644
--- a/cpukit/score/inline/rtems/score/chain.inl
+++ b/cpukit/score/inline/rtems/score/chain.inl
@@ -10,7 +10,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,9 +28,16 @@
  *  @{
  */
 
-/**
- *  This function returns TRUE if \a left and \a right are equal,
+/** @brief Are Two Nodes Equal
+ *
+ *  This function returns TRUE if @a left and @a right are equal,
  *  and FALSE otherwise.
+ *
+ *  @param[in] left is the node on the left hand side of the comparison.
+ *  @param[in] right is the node on the left hand side of the comparison.
+ *
+ *  @return This function returns TRUE if @a left and @a right are equal,
+ *          and FALSE otherwise.
  */
 RTEMS_INLINE_ROUTINE boolean _Chain_Are_nodes_equal(
   Chain_Node *left,
@@ -40,28 +47,43 @@ RTEMS_INLINE_ROUTINE boolean _Chain_Are_nodes_equal(
   return left == right;
 }
 
-/**
+/** @brief Is this Chain Control Pointer Null
+ *
  *  This function returns TRUE if the_chain is NULL and FALSE otherwise.
+ *
+ *  @param[in] the_chain is the chain to be checked for empty status.
+ *
+ *  @return This method returns TRUE if the_chain is NULL and FALSE otherwise.
  */
 RTEMS_INLINE_ROUTINE boolean _Chain_Is_null(
   Chain_Control *the_chain
 )
 {
-  return ( the_chain == NULL );
+  return (the_chain == NULL);
 }
-/**
+
+/** @brief Is the Chain Node Pointer NULL
+ *
  *  This function returns TRUE if the_node is NULL and FALSE otherwise.
+ *
+ *  @param[in] the_node is the node pointer to check.
+ *
+ *  @return This method returns TRUE if the_node is NULL and FALSE otherwise.
  */
-
 RTEMS_INLINE_ROUTINE boolean _Chain_Is_null_node(
   Chain_Node *the_node
 )
 {
-  return ( the_node == NULL );
+  return (the_node == NULL);
 }
 
-/**
+/** @brief Return pointer to Chain Head
+ *
  *  This function returns a pointer to the first node on the chain.
+ *
+ *  @param[in] the_chain is the chain to be operated upon.
+ *
+ *  @return This method returns the permanent head node of the chain.
  */
 RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Head(
   Chain_Control *the_chain
@@ -70,8 +92,13 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Head(
    return (Chain_Node *) the_chain;
 }
 
-/**
+/** @brief Return pointer to Chain Tail
+ *
  *  This function returns a pointer to the last node on the chain.
+ *
+ *  @param[in] the_chain is the chain to be operated upon.
+ *
+ *  @return This method returns the permanent tail node of the chain.
  */
 RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Tail(
   Chain_Control *the_chain
@@ -80,92 +107,132 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Tail(
    return (Chain_Node *) &the_chain->permanent_null;
 }
 
-/**
- *  This function returns TRUE if there a no nodes on the_chain and
+/** @brief Is the Chain Empty
+ *
+ *  This function returns TRUE if there a no nodes on @a the_chain and
+ *  FALSE otherwise.
+ *
+ *  @param[in] the_chain is the chain to be operated upon.
+ *
+ *  @return This function returns TRUE if there a no nodes on @a the_chain and
  *  FALSE otherwise.
  */
 RTEMS_INLINE_ROUTINE boolean _Chain_Is_empty(
   Chain_Control *the_chain
 )
 {
-  return ( the_chain->first == _Chain_Tail( the_chain ) );
+  return (the_chain->first == _Chain_Tail(the_chain));
 }
 
-/**
+/** @brief Is this the First Node on the Chain
+ *
  *  This function returns TRUE if the_node is the first node on a chain and
  *  FALSE otherwise.
+ *
+ *  @param[in] the_node is the node the caller wants to know if it is
+ *             the first node on a chain.
+ *
+ *  @return This function returns TRUE if @a the_node is the first node on
+ *          a chain and FALSE otherwise.
  */
 RTEMS_INLINE_ROUTINE boolean _Chain_Is_first(
   Chain_Node *the_node
 )
 {
-  return ( the_node->previous == NULL );
+  return (the_node->previous == NULL);
 }
 
-/**
- *  This function returns TRUE if \a the_node is the last node on a chain and
+/** @brief Is this the Last Node on the Chain
+ *
+ *  This function returns TRUE if @a the_node is the last node on a chain and
  *  FALSE otherwise.
+ *
+ *  @param[in] the_node is the node to check as the last node.
+ *
+ *  @return This function returns TRUE if @a the_node is the last node on
+ *          a chain and FALSE otherwise.
  */
 RTEMS_INLINE_ROUTINE boolean _Chain_Is_last(
   Chain_Node *the_node
 )
 {
-  return ( the_node->next == NULL );
+  return (the_node->next == NULL);
 }
 
-/**
- *  This function returns TRUE if there is only one node on \a the_chain and
+/** @brief Does this Chain have only One Node
+ *
+ *  This function returns TRUE if there is only one node on @a the_chain and
  *  FALSE otherwise.
+ *
+ *  @param[in] the_chain is the chain to be operated upon.
+ *
+ *  @return This function returns TRUE if there is only one node on
+ *          @a the_chain and FALSE otherwise.
  */
-
 RTEMS_INLINE_ROUTINE boolean _Chain_Has_only_one_node(
   Chain_Control *the_chain
 )
 {
-  return ( the_chain->first == the_chain->last );
+  return (the_chain->first == the_chain->last);
 }
 
-/**
- *  This function returns TRUE if the_node is the head of the_chain and
+/** @brief Is this Node the Chain Head
+ *
+ *  This function returns TRUE if @a the_node is the head of the_chain and
  *  FALSE otherwise.
+ *
+ *  @param[in] the_chain is the chain to be operated upon.
+ *  @param[in] the_node is the node to check for being the Chain Head.
+ *
+ *  @return This function returns TRUE if @a the_node is the head of
+ *          @a the_chain and FALSE otherwise.
  */
 RTEMS_INLINE_ROUTINE boolean _Chain_Is_head(
   Chain_Control *the_chain,
   Chain_Node    *the_node
 )
 {
-   return ( the_node == _Chain_Head( the_chain ) );
+   return (the_node == _Chain_Head(the_chain));
 }
 
-/**
+/** @brief Is this Node the Chail Tail
+ *
  *  This function returns TRUE if the_node is the tail of the_chain and
  *  FALSE otherwise.
+ *
+ *  @param[in] the_chain is the chain to be operated upon.
+ *  @param[in] the_node is the node to check for being the Chain Tail.
  */
 RTEMS_INLINE_ROUTINE boolean _Chain_Is_tail(
   Chain_Control *the_chain,
   Chain_Node    *the_node
 )
 {
-   return ( the_node == _Chain_Tail( the_chain ) );
+   return (the_node == _Chain_Tail(the_chain));
 }
 
-/**
+/** @brief Initialize this Chain as Empty
+ *
  *  This routine initializes the specified chain to contain zero nodes.
+ *
+ *  @param[in] the_chain is the chain to be initialized.
  */
-
 RTEMS_INLINE_ROUTINE void _Chain_Initialize_empty(
   Chain_Control *the_chain
 )
 {
-  the_chain->first          = _Chain_Tail( the_chain );
+  the_chain->first          = _Chain_Tail(the_chain);
   the_chain->permanent_null = NULL;
-  the_chain->last           = _Chain_Head( the_chain );
+  the_chain->last           = _Chain_Head(the_chain);
 }
 
-/**
+/** @brief Extract this Node (unprotected)
+ *
  *  This routine extracts the_node from the chain on which it resides.
- *  It does NOT disable interrupts to insure the atomicity of the
+ *  It does NOT disable interrupts to ensure the atomicity of the
  *  extract operation.
+ *
+ *  @param[in] the_node is the node to be extracted.
  */
 RTEMS_INLINE_ROUTINE void _Chain_Extract_unprotected(
   Chain_Node *the_node
@@ -180,10 +247,19 @@ RTEMS_INLINE_ROUTINE void _Chain_Extract_unprotected(
   previous->next = next;
 }
 
-/**
+/** @brief Get the First Node (unprotected)
+ *
  *  This function removes the first node from the_chain and returns
- *  a pointer to that node.  It does NOT disable interrupts to insure
+ *  a pointer to that node.  It does NOT disable interrupts to ensure
  *  the atomicity of the get operation.
+ *
+ *  @param[in] the_chain is the chain to attempt to get the first node from.
+ *
+ *  @return This method returns the first node on the chain even if it is
+ *          the Chain Tail.
+ *
+ *  @note This routine assumes that there is at least one node on the chain
+ *        and always returns a node even if it is the Chain Tail.
  */
 RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_first_unprotected(
   Chain_Control *the_chain
@@ -195,33 +271,46 @@ RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_first_unprotected(
   return_node         = the_chain->first;
   new_first           = return_node->next;
   the_chain->first    = new_first;
-  new_first->previous = _Chain_Head( the_chain );
+  new_first->previous = _Chain_Head(the_chain);
 
   return return_node;
 }
 
-/**
+/** @brief Get the First Node (unprotected)
+ *
  *  This function removes the first node from the_chain and returns
  *  a pointer to that node.  If the_chain is empty, then NULL is returned.
- *  It does NOT disable interrupts to insure the atomicity of the
- *  get operation.
+ *
+ *  @param[in] the_chain is the chain to attempt to get the first node from.
+ *
+ *  @return This method returns the first node on the chain or NULL if the
+ *          chain is empty.
+ *
+ *  @note It does NOT disable interrupts to ensure the atomicity of the
+ *        get operation.
  */
 RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Get_unprotected(
   Chain_Control *the_chain
 )
 {
-  if ( !_Chain_Is_empty( the_chain ) )
-    return _Chain_Get_first_unprotected( the_chain );
+  if ( !_Chain_Is_empty(the_chain))
+    return _Chain_Get_first_unprotected(the_chain);
   else
     return NULL;
 }
 
-/**
+/** @brief Insert a Node (unprotected)
+ *
  *  This routine inserts the_node on a chain immediately following
- *  after_node.  It does NOT disable interrupts to insure the atomicity
- *  of the extract operation.
+ *  after_node.
+ *
+ *  @param[in] after_node is the node which will precede @a the_node on the
+ *             chain.
+ *  @param[in] the_node is the node to be inserted.
+ *
+ *  @note It does NOT disable interrupts to ensure the atomicity
+ *        of the extract operation.
  */
-
 RTEMS_INLINE_ROUTINE void _Chain_Insert_unprotected(
   Chain_Node *after_node,
   Chain_Node *the_node
@@ -236,10 +325,15 @@ RTEMS_INLINE_ROUTINE void _Chain_Insert_unprotected(
   before_node->previous = the_node;
 }
 
-/**
+/** @brief Append a Node (unprotected) 
+ *
  *  This routine appends the_node onto the end of the_chain.
- *  It does NOT disable interrupts to insure the atomicity of the
- *  append operation.
+ *
+ *  @param[in] the_chain is the chain to be operated upon.
+ *  @param[in] the_node is the node to be appended.
+ *
+ *  @note It does NOT disable interrupts to ensure the atomicity of the
+ *        append operation.
  */
 RTEMS_INLINE_ROUTINE void _Chain_Append_unprotected(
   Chain_Control *the_chain,
@@ -248,37 +342,47 @@ RTEMS_INLINE_ROUTINE void _Chain_Append_unprotected(
 {
   Chain_Node *old_last_node;
 
-  the_node->next      = _Chain_Tail( the_chain );
+  the_node->next      = _Chain_Tail(the_chain);
   old_last_node       = the_chain->last;
   the_chain->last     = the_node;
   old_last_node->next = the_node;
   the_node->previous  = old_last_node;
 }
 
-/**
+/** @brief Prepend a Node (unprotected)
+ *
  *  This routine prepends the_node onto the front of the_chain.
- *  It does NOT disable interrupts to insure the atomicity of the
- *  prepend operation.
+ *
+ *  @param[in] the_chain is the chain to be operated upon.
+ *  @param[in] the_node is the node to be prepended.
+ *
+ *  @note It does NOT disable interrupts to ensure the atomicity of the
+ *        prepend operation.
  */
 RTEMS_INLINE_ROUTINE void _Chain_Prepend_unprotected(
   Chain_Control *the_chain,
   Chain_Node    *the_node
 )
 {
-  _Chain_Insert_unprotected( _Chain_Head( the_chain ), the_node );
+  _Chain_Insert_unprotected(_Chain_Head(the_chain), the_node);
 }
 
-/**
+/** @brief Prepend a Node (protected)
+ *
  *  This routine prepends the_node onto the front of the_chain.
- *  It disables interrupts to insure the atomicity of the
- *  prepend operation.
+ *
+ *  @param[in] the_chain is the chain to be operated upon.
+ *  @param[in] the_node is the node to be prepended.
+ *
+ *  @note It disables interrupts to ensure the atomicity of the
+ *        prepend operation.
  */
 RTEMS_INLINE_ROUTINE void _Chain_Prepend(
   Chain_Control *the_chain,
   Chain_Node    *the_node
 )
 {
-  _Chain_Insert( _Chain_Head( the_chain ), the_node );
+  _Chain_Insert(_Chain_Head(the_chain), the_node);
 }
 
 /**@}*/