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

diff --git a/cpukit/score/include/rtems/score/apimutex.h b/cpukit/score/include/rtems/score/apimutex.h
index ed345c7c76..ad30e0b18b 100644
--- a/cpukit/score/include/rtems/score/apimutex.h
+++ b/cpukit/score/include/rtems/score/apimutex.h
@@ -1,10 +1,13 @@
-/*  apimutex.h
+/** 
+ *  @file apimutex.h
  *
  *  This include file contains all the constants and structures associated
  *  with the API Mutex Handler.  This handler is used by API level
  *  routines to manage mutual exclusion.
- *
- *  COPYRIGHT (c) 1989-2002.
+ */
+
+/*
+ *  COPYRIGHT (c) 1989-2004.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be
@@ -17,6 +20,14 @@
 #ifndef __API_MUTEX_h
 #define __API_MUTEX_h
 
+/**
+ *  @defgroup ScoreAPIMutex API Mutex Handler
+ *
+ *  This group contains functionality which provides mutexes to be used
+ *  in the implementation of API functionality. 
+ */
+/**@{*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -25,30 +36,29 @@ extern "C" {
 #include <rtems/score/isr.h>
 #include <rtems/score/object.h>
 
-/*
- *  The following defines the control block used to manage each mutex.
+/**
+ *  The following defines the control block used to manage each API mutex.
+ *  An API Mutex is an aggregration of an Object and a SuperCore Mutex.
  */
-
 typedef struct {
+  /** This field allows each API Mutex to be a full-fledged RTEMS object.
   Objects_Control       Object;
+  /** This field contains the SuperCore mutex information. */
   CORE_mutex_Control    Mutex;
 }   API_Mutex_Control;
 
-/*
- *  The following defines the information control block used to manage
+/**
+ *  The following variable is the information control block used to manage
  *  this class of objects.
  */
-
 SCORE_EXTERN Objects_Information  _API_Mutex_Information;
 
-/*
- *  _API_Mutex_Initialization
- *
- *  DESCRIPTION:
- *
+/**
  *  This routine performs the initialization necessary for this handler.
+ *
+ *  @param _maximum_mutexes (in) is the maximum number of API mutexes
+ *         that may exist at any time
  */
-
 #if defined(RTEMS_MULTIPROCESSING)
 #define _API_Mutex_Initialization( _maximum_mutexes ) \
   _Objects_Initialize_information( \
@@ -75,14 +85,11 @@ SCORE_EXTERN Objects_Information  _API_Mutex_Information;
   );
 #endif
 
-/*
- *  _API_Mutex_Allocate
- *
- *  DESCRIPTION:
+/**
+ *  This routine allocates an API mutex from the inactive set.
  *
- *  This routine allocates an api mutex from the inactive set.
+ *  @param _the_mutex (out) will contain the allocated mutex.
  */
-
 #define _API_Mutex_Allocate( _the_mutex ) \
   do { \
     CORE_mutex_Attributes attr =  \
@@ -94,14 +101,11 @@ SCORE_EXTERN Objects_Information  _API_Mutex_Information;
        &(_the_mutex)->Mutex, &attr, CORE_MUTEX_UNLOCKED ); \
   } while (0)
 
-/*
- *  _API_Mutex_Lock
+/**
+ *  This routine acquires the specified API mutex.
  *
- *  DESCRIPTION:
- *
- *  This routine acquires the specified api mutex.
+ *  @param _the_mutex (in) is the mutex to acquire.
  */
-
 #define _API_Mutex_Lock( _the_mutex ) \
   do { \
     ISR_Level _level;  \
@@ -110,12 +114,10 @@ SCORE_EXTERN Objects_Information  _API_Mutex_Information;
       &(_the_mutex)->Mutex, (_the_mutex)->Object.id, TRUE, 0, (_level) ); \
   } while (0)
 
-/*
- *  _API_Mutex_Unlock
- *
- *  DESCRIPTION:
+/**
+ *  This routine releases the specified API mutex.
  *
- *  This routine releases the specified api mutex.
+ *  @param _the_mutex (in) is the mutex to release.
  */
 
 #define _API_Mutex_Unlock( _the_mutex ) \
@@ -126,15 +128,29 @@ SCORE_EXTERN Objects_Information  _API_Mutex_Information;
     _Thread_Enable_dispatch(); \
   } while (0);
 
-/*XXX when the APIs all use this for allocation and deallocation
- *XXX protection, then they should be renamed and probably moved
+/**
+ *  This variable points to the API Mutex instance that is used
+ *  to protect all memory allocation and deallocation in RTEMS.
+ *
+ *  @note When the APIs all use this for allocation and deallocation
+ *  protection, then this possibly should be renamed and moved to a
+ *  higher level in the hierarchy.
  */
-
 SCORE_EXTERN API_Mutex_Control  *_RTEMS_Allocator_Mutex;
 
+/**
+ *  This macro locks the RTEMS Allocation Mutex.
+ *
+ *  @see _RTEMS_Allocator_Mutex
+ */
 #define _RTEMS_Lock_allocator() \
   _API_Mutex_Lock( _RTEMS_Allocator_Mutex )
 
+/**
+ *  This macro unlocks the RTEMS Allocation Mutex.
+ *
+ *  @see _RTEMS_Allocator_Mutex
+ */
 #define _RTEMS_Unlock_allocator() \
   _API_Mutex_Unlock( _RTEMS_Allocator_Mutex )
 
@@ -150,5 +166,7 @@ SCORE_EXTERN API_Mutex_Control  *_RTEMS_Allocator_Mutex;
 }
 #endif
 
+/*!@}*/
+
 #endif
 /*  end of include file */