2004-11-01 Joel Sherrill <joel@oarcorp.com>

	* score/cpu/no_cpu/rtems/score/cpu.h, 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/copyrt.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/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/coremsg.inl,
	score/inline/rtems/score/coremutex.inl,
	score/inline/rtems/score/coresem.inl,
	score/inline/rtems/score/heap.inl, score/inline/rtems/score/isr.inl,
	score/inline/rtems/score/mppkt.inl,
	score/inline/rtems/score/objectmp.inl,
	score/inline/rtems/score/priority.inl,
	score/inline/rtems/score/stack.inl,
	score/inline/rtems/score/states.inl,
	score/inline/rtems/score/sysstate.inl,
	score/inline/rtems/score/thread.inl,
	score/inline/rtems/score/threadmp.inl,
	score/inline/rtems/score/tod.inl,
	score/inline/rtems/score/tqdata.inl,
	score/inline/rtems/score/userext.inl,
	score/inline/rtems/score/watchdog.inl,
	score/inline/rtems/score/wkspace.inl: Add Doxygen comments -- working
	modifications which are not complete and may have broken code.
	Committing so work and testing can proceed.
	* score/Doxyfile, score/mainpage.h: New files.

1 files changed, 99 insertions, 67 deletions

diff --git a/cpukit/score/include/rtems/score/watchdog.h b/cpukit/score/include/rtems/score/watchdog.h
index cb70d13120..91d2a166c0 100644
--- a/cpukit/score/include/rtems/score/watchdog.h
+++ b/cpukit/score/include/rtems/score/watchdog.h
@@ -1,10 +1,13 @@
-/*  watchdog.h
+/** 
+ *  @file watchdog.h
  *
  *  This include file contains all the constants and structures associated
  *  with watchdog timers.   This Handler provides mechanisms which can be
- *   used to initialize and manipulate watchdog timers.
- *
- *  COPYRIGHT (c) 1989-1999.
+ *  used to initialize and manipulate watchdog timers.
+ */
+
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be
@@ -17,67 +20,94 @@
 #ifndef __WATCHDOG_h
 #define __WATCHDOG_h
 
+/**
+ *  @defgroup ScoreWatchdog Watchdog Handler
+ *
+ *  This group contains functionality which XXX
+ */
+/**@{*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 #include <rtems/score/object.h>
 
-/*
+/** @brief Maximum Interval Length
+ *
  *  The following type defines the control block used to manage
  *  intervals.
  */
-
 #define WATCHDOG_MAXIMUM_INTERVAL ((Watchdog_Interval) 0xffffffff)
 
+/** @brief Watchdog Interval Type
+ *
+ *  This type is used to specify the length of intervals.
+ */
 typedef uint32_t   Watchdog_Interval;
 
-/*
- *  The following types define a pointer to a watchdog service routine.
+/** @brief Watchdog Service Routine Return Type
+ * 
+ *  This type defines the return type from a Watchdog Service Routine.
  */
-
 typedef void Watchdog_Service_routine;
 
+/** @brief Watchdog Service Routine Pointer Type
+ *
+ *  This type define a pointer to a watchdog service routine.
+ */
 typedef Watchdog_Service_routine ( *Watchdog_Service_routine_entry )(
                  Objects_Id,
                  void *
              );
 
-/*
- *  Constant for indefinite wait.  (actually an illegal interval)
+/** @brief No timeout constant
+ *
+ *  This is the constant for indefinite wait.  It is actually an
+ *  illegal interval.
  */
-
 #define WATCHDOG_NO_TIMEOUT  0
 
-/*
- *  The following enumerated type lists the states in which a
+/** @brief Watchdog States Type
+ *
+ *  This enumerated type is the set of the states in which a
  *  watchdog timer may be at any given time.
  */
 
 typedef enum {
-  WATCHDOG_INACTIVE,       /* off all chains */
-  WATCHDOG_BEING_INSERTED, /* off all chains, searching for insertion point */
-  WATCHDOG_ACTIVE,         /* on chain, allowed to fire */
-  WATCHDOG_REMOVE_IT       /* on chain, remove without firing if expires */
+  /** This is the state when the watchdog is off all chains */
+  WATCHDOG_INACTIVE,
+  /** This is the state when the watchdog is off all chains, but we are
+   *  currently searching for the insertion point.
+   */
+  WATCHDOG_BEING_INSERTED,
+  /** This is the state when the watchdog is on a chain, and allowed to fire. */
+  WATCHDOG_ACTIVE,
+  /** This is the state when the watchdog is on a chain, but we should
+   *  remove without firing if it expires.
+   */
+  WATCHDOG_REMOVE_IT
 } Watchdog_States;
 
-/*
+/** @brief Watchdog Adjustment Directions Type
+ *
  *  The following enumerated type details the manner in which
- *  a watchdog chain may be adjusted by the Watchdog_Adjust
+ *  a watchdog chain may be adjusted by the @ref _Watchdog_Adjust
  *  routine.  The direction indicates a movement FORWARD
  *  or BACKWARD in time.
  */
-
 typedef enum {
-  WATCHDOG_FORWARD,      /* adjust delta value forward */
-  WATCHDOG_BACKWARD      /* adjust delta value backward */
+  /** adjust delta value forward */
+  WATCHDOG_FORWARD,
+  /** adjust delta value backward */
+  WATCHDOG_BACKWARD
 } Watchdog_Adjust_directions;
 
-/*
+/** @brief Watchdog Control Structure
+ *
  *  The following record defines the control block used
  *  to manage each watchdog timer.
  */
-
 typedef struct {
   Chain_Node                      Node;
   Watchdog_States                 state;
@@ -90,93 +120,93 @@ typedef struct {
   void                           *user_data;
 }   Watchdog_Control;
 
-/*
- *  The following are used for synchronization purposes
+/** @brief Watchdog Synchronization Level
+ *
+ *  This used for synchronization purposes
  *  during an insert on a watchdog delta chain.
  */
-
 SCORE_EXTERN volatile uint32_t    _Watchdog_Sync_level;
+
+/** @brief Watchdog Synchronization Count
+ *
+ *  This used for synchronization purposes
+ *  during an insert on a watchdog delta chain.
+ */
 SCORE_EXTERN volatile uint32_t    _Watchdog_Sync_count;
 
-/*
- *  The following contains the number of ticks since the
- *  system was booted.
+/** @brief Ticks Since System Boot
+ *
+ *  This contains the number of ticks since the system was booted.
  */
 
 SCORE_EXTERN volatile Watchdog_Interval _Watchdog_Ticks_since_boot;
 
-/*
- *  The following defines the watchdog chains which are managed
- *  on ticks and second boundaries.
+/** @brief Per Ticks Watchdog List
+ *
+ *  This is the watchdog chain which is managed at ticks.
  */
-
 SCORE_EXTERN Chain_Control _Watchdog_Ticks_chain;
-SCORE_EXTERN Chain_Control _Watchdog_Seconds_chain;
 
-/*
- *  _Watchdog_Handler_initialization
+/** @brief Per Seconds Watchdog List
  *
- *  DESCRIPTION:
+ *  This is the watchdog chain which is managed at second boundaries.
+ */
+SCORE_EXTERN Chain_Control _Watchdog_Seconds_chain;
+
+/** @brief Watchdog Handler Initialization
  *
  *  This routine initializes the watchdog handler.  The watchdog
  *  synchronization flag is initialized and the watchdog chains are
  *  initialized and emptied.
  */
-
 void _Watchdog_Handler_initialization( void );
 
-/*
- *  _Watchdog_Remove
- *
- *  DESCRIPTION:
+/** @brief Remove Watchdog from List
  *
- *  This routine removes THE_WATCHDOG from the watchdog chain on which
- *  it resides and returns the state THE_WATCHDOG timer was in.
+ *  This routine removes @a the_watchdog from the watchdog chain on which
+ *  it resides and returns the state @a the_watchdog timer was in.
+ *  
+ *  @param the_watchdog (in) will be removed
+ *  @return the state in which @a the_watchdog was in when removed
  */
-
 Watchdog_States _Watchdog_Remove (
   Watchdog_Control *the_watchdog
 );
 
-/*
- *  _Watchdog_Adjust
+/** @brief Watchdog Adjust
  *
- *  DESCRIPTION:
+ *  This routine adjusts the @a header watchdog chain in the forward
+ *  or backward @a direction for @a units ticks.
  *
- *  This routine adjusts the HEADER watchdog chain in the forward
- *  or backward DIRECTION for UNITS ticks.
+ *  @param header (in) is the watchdog chain to adjust
+ *  @param direction (in) is the direction to adjust @a header
+ *  @param units (in) is the number of units to adjust @a header
  */
-
 void _Watchdog_Adjust (
   Chain_Control              *header,
   Watchdog_Adjust_directions  direction,
   Watchdog_Interval           units
 );
 
-/*
- *  _Watchdog_Insert
- *
- *  DESCRIPTION:
+/** @brief Watchdog Insert
  *
- *  This routine inserts THE_WATCHDOG into the HEADER watchdog chain
- *  for a time of UNITS.  The INSERT_MODE indicates whether
- *  THE_WATCHDOG is to be activated automatically or later, explicitly
- *  by the caller.
+ *  This routine inserts @a the_watchdog into the @a header watchdog chain
+ *  for a time of @a units.  
  *
+ *  @param header (in) is @a the_watchdog list to insert @a the_watchdog on
+ *  @param the_watchdog (in) is the watchdog to insert
  */
-
 void _Watchdog_Insert (
   Chain_Control         *header,
   Watchdog_Control      *the_watchdog
 );
 
-/*
- *  _Watchdog_Tickle
- *
- *  DESCRIPTION:
+/** @brief Watchdog Tickle
  *
  *  This routine is invoked at appropriate intervals to update
- *  the HEADER watchdog chain.
+ *  the @a header watchdog chain.
+ *
+ *  @param header (in) is the watchdog chain to tickle
  */
 
 void _Watchdog_Tickle (
@@ -191,5 +221,7 @@ void _Watchdog_Tickle (
 }
 #endif
 
+/**@}*/
+
 #endif
 /* end of include file */