2008-06-06 Joel Sherrill <joel.sherrill@oarcorp.com>

	* rtems/include/rtems.h, rtems/include/rtems/rtems/clock.h,
	rtems/include/rtems/rtems/config.h,
	rtems/include/rtems/rtems/dpmem.h,
	rtems/include/rtems/rtems/eventset.h,
	rtems/include/rtems/rtems/object.h, rtems/include/rtems/rtems/part.h,
	rtems/include/rtems/rtems/ratemon.h,
	rtems/include/rtems/rtems/region.h, rtems/include/rtems/rtems/sem.h,
	rtems/include/rtems/rtems/tasks.h, rtems/include/rtems/rtems/timer.h,
	rtems/include/rtems/rtems/types.h, rtems/src/ratemonperiod.c: Improve
	Classic API Doxygen.

13 files changed, 423 insertions, 67 deletions

diff --git a/cpukit/rtems/include/rtems.h b/cpukit/rtems/include/rtems.h
index 49cf5f76e0..8eb91f12fa 100644
--- a/cpukit/rtems/include/rtems.h
+++ b/cpukit/rtems/include/rtems.h
@@ -1,10 +1,8 @@
 /**
  * @file  rtems.h
  *
- *  This include file contains information about RTEMS executive that
- *  is required by the application and is CPU independent.  It includes
- *  two (2) CPU dependent files to tailor its data structures for a
- *  particular processor.
+ *  This include file provides the public interface to the RTEMS Classic
+ *  API.
  */
 
 /*  COPYRIGHT (c) 1989-2008.
@@ -23,7 +21,8 @@
 /**
  *  @defgroup ClassicRTEMS Classic API RTEMS Header
  *
- *  This encapsulates functionality which XXX
+ *  This encapsulates functionality which is specific to the Classic API
+ *  and generally shared across the various object classes.
  */
 /**@{*/
 
@@ -42,7 +41,6 @@ extern "C" {
  *  which are not included in the formally defined and supported API.
  *  Define this at your own risk.
  */
-
 #define __RTEMS_APPLICATION__
 #endif
 
@@ -85,9 +83,9 @@ extern "C" {
  */
 #define RTEMS_HAS_HARDWARE_FP CPU_HARDWARE_FP
 
-/*
- *  The following define the constants which may be used in name searches.
- */
+/**********************************************************************
+ *      CONSTANTS WHICH MAY BE USED IN OBJECT NAME TO ID SEARCHES
+ **********************************************************************/ 
 
 /**
  * This constant indicates that the search is across all nodes.
@@ -115,9 +113,9 @@ extern "C" {
  */
 #define RTEMS_WHO_AM_I           OBJECTS_WHO_AM_I
 
-/*
- * Parameters and return id's for _Objects_Get_next
- */
+/**********************************************************************
+ *        Parameters and return Id's for _Objects_Get_next
+ **********************************************************************/ 
 
 /**
  *  This constant is the lowest valid valid for the index portion
diff --git a/cpukit/rtems/include/rtems/rtems/clock.h b/cpukit/rtems/include/rtems/rtems/clock.h
index a6fc6bbb6a..721e30ae35 100644
--- a/cpukit/rtems/include/rtems/rtems/clock.h
+++ b/cpukit/rtems/include/rtems/rtems/clock.h
@@ -63,7 +63,9 @@ typedef enum {
  *  Standard flavor style to return TOD in for a rtems_clock_get option.
  */
 typedef struct {
+  /** This is the seconds portion of a time of day. */
   uint32_t    seconds;
+  /** This is the microseconds portion of a time of day. */
   uint32_t    microseconds;
 } rtems_clock_time_value;
 
diff --git a/cpukit/rtems/include/rtems/rtems/config.h b/cpukit/rtems/include/rtems/rtems/config.h
index 1c7866ae8d..5afc3063d4 100644
--- a/cpukit/rtems/include/rtems/rtems/config.h
+++ b/cpukit/rtems/include/rtems/rtems/config.h
@@ -41,16 +41,72 @@ extern "C" {
  *     + required number of each object type
  */
 typedef struct {
+  /**
+   * This field contains the maximum number of Classic API 
+   * Tasks which are configured for this application.
+   */
   uint32_t                    maximum_tasks;
+
+  /**
+   * This field contains the maximum number of Classic API 
+   * Timers which are configured for this application.
+   */
   uint32_t                    maximum_timers;
+
+  /**
+   * This field contains the maximum number of Classic API 
+   * Semaphores which are configured for this application.
+   */
   uint32_t                    maximum_semaphores;
+
+  /**
+   * This field contains the maximum number of Classic API 
+   * Message Queues which are configured for this application.
+   */
   uint32_t                    maximum_message_queues;
+
+  /**
+   * This field contains the maximum number of Classic API 
+   * Partitions which are configured for this application.
+   */
   uint32_t                    maximum_partitions;
+
+  /**
+   * This field contains the maximum number of Classic API 
+   * Regions which are configured for this application.
+   */
   uint32_t                    maximum_regions;
+
+  /**
+   * This field contains the maximum number of Classic API 
+   * Dual Ported Memory Areas which are configured for this
+   * application.
+   */
   uint32_t                    maximum_ports;
+
+  /**
+   * This field contains the maximum number of Classic API 
+   * Rate Monotonic Periods which are configured for this
+   * application.
+   */
   uint32_t                    maximum_periods;
+
+  /**
+   * This field contains the maximum number of Classic API 
+   * Barriers which are configured for this application.
+   */
   uint32_t                    maximum_barriers;
+
+  /**
+   * This field contains the number of Classic API Initialization
+   * Tasks which are configured for this application.
+   */
   uint32_t                    number_of_initialization_tasks;
+
+  /**
+   * This field is the set of Classic API Initialization
+   * Tasks which are configured for this application.
+   */
   rtems_initialization_tasks_table *User_initialization_tasks_table;
 } rtems_api_configuration_table;
 
diff --git a/cpukit/rtems/include/rtems/rtems/dpmem.h b/cpukit/rtems/include/rtems/rtems/dpmem.h
index 5a16107471..5a862c6984 100644
--- a/cpukit/rtems/include/rtems/rtems/dpmem.h
+++ b/cpukit/rtems/include/rtems/rtems/dpmem.h
@@ -50,7 +50,8 @@ extern "C" {
 /**
  *  @defgroup ClassicDPMEM Classic API Dual Ported Memory
  *
- *  This encapsulates functionality which XXX
+ *  This encapsulates functionality related to the
+ *  Classic API Dual Ported Memory Manager.
  */
 /**@{*/
 
@@ -60,10 +61,14 @@ extern "C" {
  *  all information required to support the port related operations.
  */
 typedef struct {
+  /** This field is the object management portion of a Port instance. */
   Objects_Control  Object;
-  void            *internal_base; /* base internal address */
-  void            *external_base; /* base external address */
-  uint32_t         length;        /* length of dual-ported area */
+  /** This field is the base internal address of the port. */
+  void            *internal_base;
+  /** This field is the base external address of the port. */
+  void            *external_base;
+  /** This field is the length of dual-ported area of the port. */
+  uint32_t         length;
 }   Dual_ported_memory_Control;
 
 /**
diff --git a/cpukit/rtems/include/rtems/rtems/eventset.h b/cpukit/rtems/include/rtems/rtems/eventset.h
index c6e991bb96..e8e50bd06f 100644
--- a/cpukit/rtems/include/rtems/rtems/eventset.h
+++ b/cpukit/rtems/include/rtems/rtems/eventset.h
@@ -22,7 +22,8 @@
 /**
  *  @defgroup ClassicEventSet Classic API Event Set
  *
- *  This encapsulates functionality which XXX
+ *  This encapsulates functionality related to Classic API
+ *  Event Sets.  These are used by the Classic API Event Manager.
  */
 /**@{*/
 
diff --git a/cpukit/rtems/include/rtems/rtems/object.h b/cpukit/rtems/include/rtems/rtems/object.h
index 367e5ef224..6e8d6a9f4f 100644
--- a/cpukit/rtems/include/rtems/rtems/object.h
+++ b/cpukit/rtems/include/rtems/rtems/object.h
@@ -97,7 +97,7 @@ typedef struct {
  *  @note The object must be have a name of the 32-bit form.
  *
  *  @return @a *name will contain user defined object name
- *  @return @a{RTEMS_SUCCESSFUL - if successful
+ *  @return @a RTEMS_SUCCESSFUL - if successful
  *  @return error code - if unsuccessful
  */
 rtems_status_code rtems_object_get_classic_name(
@@ -149,7 +149,7 @@ rtems_status_code rtems_object_set_name(
  *
  *  This function returns the API portion of the Id.
  *
- *  @param[in] id is the Id of the object to obtain the API from
+ *  @param[in] _id is the Id of the object to obtain the API from
  *
  *  @return This method returns the API portion of the provided
  *          @a _id.
@@ -166,7 +166,7 @@ rtems_status_code rtems_object_set_name(
  *
  *  This function returns the class portion of the ID.
  *
- *  @param[in] id is the Id of the object to obtain the class from
+ *  @param[in] _id is the Id of the object to obtain the class from
  *
  *  @return This method returns the class portion of the provided
  *          @a _id.
@@ -183,7 +183,7 @@ rtems_status_code rtems_object_set_name(
  *
  *  This function returns the node portion of the ID.
  *
- *  @param[in] id is the Id of the object to obtain the node from
+ *  @param[in] _id is the Id of the object to obtain the node from
  *
  *  @return This method returns the node portion of the provided
  *          @a _id.
@@ -200,7 +200,7 @@ rtems_status_code rtems_object_set_name(
  *
  *  This function returns the index portion of the ID.
  *
- *  @param[in] id is the Id of the object to obtain the index from
+ *  @param[in] _id is the Id of the object to obtain the index from
  *
  *  @return This method returns the index portion of the provided
  *          @a _id.
diff --git a/cpukit/rtems/include/rtems/rtems/part.h b/cpukit/rtems/include/rtems/rtems/part.h
index 3e1843978a..32b23ded6b 100644
--- a/cpukit/rtems/include/rtems/rtems/part.h
+++ b/cpukit/rtems/include/rtems/rtems/part.h
@@ -52,7 +52,8 @@ extern "C" {
 /**
  *  @defgroup ClassicPart Classic API Partition
  *
- *  This encapsulates functionality which XXX
+ *  This encapsulates functionality related to the
+ *  Classic API Partition Manager.
  */
 /**@{*/
 
@@ -60,13 +61,20 @@ extern "C" {
  *  The following defines the control block used to manage each partition.
  */
 typedef struct {
+  /** This field is the object management portion of a Partition instance. */
   Objects_Control     Object;
-  void               *starting_address;      /* physical address */
-  uint32_t            length;                /* in bytes */
-  uint32_t            buffer_size;           /* in bytes */
-  rtems_attribute  attribute_set;         /* attributes */
-  uint32_t            number_of_used_blocks; /* or allocated buffers */
-  Chain_Control       Memory;                /* buffer chain */
+  /** This field is the physical starting address of the Partition. */
+  void               *starting_address;
+  /** This field is the size of the Partition in bytes. */
+  uint32_t            length;
+  /** This field is the size of each buffer in bytes */
+  uint32_t            buffer_size;
+  /** This field is the attribute set provided at create time. */
+  rtems_attribute     attribute_set;
+  /** This field is the of allocated buffers. */
+  uint32_t            number_of_used_blocks;
+  /** This field is the chain used to manage unallocated buffers. */
+  Chain_Control       Memory;
 }   Partition_Control;
 
 /**
diff --git a/cpukit/rtems/include/rtems/rtems/ratemon.h b/cpukit/rtems/include/rtems/rtems/ratemon.h
index cccf40dd9f..d1dfbeb64d 100644
--- a/cpukit/rtems/include/rtems/rtems/ratemon.h
+++ b/cpukit/rtems/include/rtems/rtems/ratemon.h
@@ -42,7 +42,8 @@
 /**
  *  @defgroup ClassicRateMon Classic API Rate Monotonic
  *
- *  This encapsulates functionality which XXX
+ *  This encapsulates functionality related to the
+ *  Classic API Rate Monotonic Manager.
  */
 /**@{*/
 
@@ -54,7 +55,7 @@ extern "C" {
  *  The user can define this at configure time and go back to ticks
  *  resolution.
  */
-#ifndef __RTEMS_USE_TICKS_RATE_MONOTONIC_STATISTICS__
+#if defined(__RTEMS_USE_TICKS_RATE_MONOTONIC_STATISTICS__)
   /**
    *  Enable the nanosecond accurate statistics
    *
@@ -62,9 +63,14 @@ extern "C" {
    *  is used.
    */
   #define RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS
+#endif
 
+/**
+ *  This is the type used to manage the rate monotonic timing
+ *  statistics.
+ */
+#if defined(RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS)
   typedef struct timespec rtems_rate_monotonic_period_time_t;
-
 #else
   typedef uint32_t rtems_rate_monotonic_period_time_t;
 #endif
@@ -83,13 +89,37 @@ extern "C" {
  *  period may be.
  */
 typedef enum {
-  RATE_MONOTONIC_INACTIVE,               /* off chain, never initialized */
-  RATE_MONOTONIC_OWNER_IS_BLOCKING,      /* on chain, owner is blocking on it */
-  RATE_MONOTONIC_ACTIVE,                 /* on chain, running continuously */
-  RATE_MONOTONIC_EXPIRED_WHILE_BLOCKING, /* on chain, expired while owner was */
-                                         /*   was blocking on it */
-  RATE_MONOTONIC_EXPIRED                 /* off chain, will be reset by next */
-                                         /*   rtems_rate_monotonic_period */
+  /**
+   * This value indicates the period is off the watchdog chain, 
+   * and has never been initialized.
+   */
+  RATE_MONOTONIC_INACTIVE,
+
+  /**
+   * This value indicates the period is on the watchdog chain, and 
+   * the owner is blocked waiting on it.
+   */
+  RATE_MONOTONIC_OWNER_IS_BLOCKING,
+
+  /**
+   * This value indicates the period is on the watchdog chain, and 
+   * running.  The owner should be executed or blocked waiting on
+   * another object.
+   */
+  RATE_MONOTONIC_ACTIVE,
+
+  /**
+   * This value indicates the period is on the watchdog chain, and 
+   * has expired.  The owner should be blocked waiting for the next period.
+   */
+  RATE_MONOTONIC_EXPIRED_WHILE_BLOCKING,
+
+  /**
+   * This value indicates the period is off the watchdog chain, and 
+   * has expired.  The owner is still executing and has taken too much
+   * all time to complete this iteration of the period.
+   */
+  RATE_MONOTONIC_EXPIRED,
 }   rtems_rate_monotonic_period_states;
 
 /**
@@ -102,15 +132,23 @@ typedef enum {
  *  The following defines the statistics kept on each period instance.
  */
 typedef struct {
+  /** This field contains the number of periods executed. */
   uint32_t     count;
+  /** This field contains the number of periods missed. */
   uint32_t     missed_count;
 
+  /** This field contains the least amount of CPU time used in a period. */
   rtems_thread_cpu_usage_t             min_cpu_time;
+  /** This field contains the highest amount of CPU time used in a period. */
   rtems_thread_cpu_usage_t             max_cpu_time;
+  /** This field contains the total amount of wall time used in a period. */
   rtems_thread_cpu_usage_t             total_cpu_time;
 
+  /** This field contains the least amount of wall time used in a period. */
   rtems_rate_monotonic_period_time_t   min_wall_time;
+  /** This field contains the highest amount of wall time used in a period. */
   rtems_rate_monotonic_period_time_t   max_wall_time;
+  /** This field contains the total amount of CPU time used in a period. */
   rtems_rate_monotonic_period_time_t   total_wall_time;
 }  rtems_rate_monotonic_period_statistics;
 
@@ -118,9 +156,24 @@ typedef struct {
  *  The following defines the period status structure.
  */
 typedef struct {
+  /** This is the Id of the thread using this period. */
   Objects_Id                           owner;
+
+  /** This is the current state of this period. */
   rtems_rate_monotonic_period_states   state;
+
+  /**
+   *  This is the length of wall time that has passed since this period
+   *  was last initiated.  If the period is expired or has not been initiated,
+   *  then this field has no meaning.
+   */
   rtems_rate_monotonic_period_time_t   since_last_period;
+
+  /**
+   *  This is the amount of CPU time that has been used since this period
+   *  was last initiated.  If the period is expired or has not been initiated,
+   *  then this field has no meaning.
+   */
   rtems_thread_cpu_usage_t             executed_since_last_period;
 }  rtems_rate_monotonic_period_status;
 
@@ -129,13 +182,43 @@ typedef struct {
  *  each period.
  */
 typedef struct {
+  /** This field is the object management portion of a Period instance. */
   Objects_Control                         Object;
+
+  /** This is the timer used to provide the unblocking mechanism. */
   Watchdog_Control                        Timer;
+
+  /** This field indicates the current state of the period. */
   rtems_rate_monotonic_period_states      state;
+
+  /**
+   * This field contains the total CPU usage used while executing
+   * the body of the loop that is executed each period.
+   */
   rtems_thread_cpu_usage_t                owner_executed_at_period;
+
+  /**
+   * This field contains the total wall timer that passed while
+   * executing the body of the loop that is executed each period.
+   */
   rtems_rate_monotonic_period_time_t      time_at_period;
+
+  /**
+   * This field contains the length of the next period to be
+   * executed.
+   */
   uint32_t                                next_length;
+
+  /**
+   * This field contains a pointer to the TCB for the thread
+   * which owns and uses this period instance.
+   */
   Thread_Control                         *owner;
+
+  /**
+   * This field contains the statistics which are maintained
+   * on each period.
+   */
   rtems_rate_monotonic_period_statistics  Statistics;
 }   Rate_monotonic_Control;
  
@@ -148,7 +231,7 @@ typedef struct {
 RTEMS_RATEMON_EXTERN Objects_Information _Rate_monotonic_Information;
 
 /**
- *  _Rate_monotonic_Manager_initialization
+ *  @brief Rate Monotonic Manager Initialization
  *
  *  This routine performs the initialization necessary for this manager.
  */
diff --git a/cpukit/rtems/include/rtems/rtems/region.h b/cpukit/rtems/include/rtems/rtems/region.h
index 74d66ea334..7f071bfcb5 100644
--- a/cpukit/rtems/include/rtems/rtems/region.h
+++ b/cpukit/rtems/include/rtems/rtems/region.h
@@ -66,14 +66,53 @@ extern "C" {
  */
 
 typedef struct {
+  /**
+   * This field is the object management portion of a Region instance.
+   */
   Objects_Control       Object;
-  Thread_queue_Control  Wait_queue;            /* waiting threads        */
-  void                 *starting_address;      /* physical start addr    */
-  uint32_t              length;                /* physical length(bytes) */
-  uint32_t              page_size;             /* in bytes               */
-  uint32_t              maximum_segment_size;  /* in bytes               */
+
+  /**
+   * This is the set of threads blocked waiting on memory.
+   */
+  Thread_queue_Control  Wait_queue;
+
+  /**
+   * This is the physical starting address of the Region area.
+   */
+  void                 *starting_address;
+
+  /**
+   * This is the physical length (in bytes) of the Region memory.
+   */
+  uint32_t              length;
+
+  /**
+   * This is the physical page size (in bytes) of each allocated segment.
+   */
+  uint32_t              page_size;
+
+  /**
+   * This is the maximum segment size (in bytes) that can ever be allocated
+   * from this Region.  It is calculated at creation time.
+   */
+  uint32_t              maximum_segment_size;
+
+  /**
+   *  This is the Classic API attribute provided to the create directive.
+   *  It is translated into behavioral attributes on the SuperCore Heap
+   *  instance.
+   */
   rtems_attribute       attribute_set;
-  uint32_t              number_of_used_blocks; /* blocks allocated       */
+
+  /**
+   * This is the number of blocks currently allocated from this Region.
+   */
+  uint32_t              number_of_used_blocks;
+
+  /**
+   * This is the Heap instance which implements the core functionality
+   * of a Region instance.
+   */
   Heap_Control          Memory;
 }  Region_Control;
 
diff --git a/cpukit/rtems/include/rtems/rtems/sem.h b/cpukit/rtems/include/rtems/rtems/sem.h
index 656717d653..f58ef5ec36 100644
--- a/cpukit/rtems/include/rtems/rtems/sem.h
+++ b/cpukit/rtems/include/rtems/rtems/sem.h
@@ -53,7 +53,8 @@ extern "C" {
 /**
  *  @defgroup ClassicSem Classic API Semaphore
  *
- *  This encapsulates functionality which XXX
+ *  This encapsulates functionality related to the Classic API
+ *  Semaphore Manager.
  */
 /**@{*/
 
@@ -61,10 +62,36 @@ extern "C" {
  *  The following defines the control block used to manage each semaphore.
  */
 typedef struct {
+  /** This field is the object management portion of a Semaphore instance. */
   Objects_Control          Object;
+
+  /**
+   *  This is the Classic API attribute provided to the create directive.
+   *  It is translated into behavioral attributes on the SuperCore Semaphore
+   *  or Mutex instance.
+   */
   rtems_attribute          attribute_set;
+
+  /**
+   *  This contains the memory associated with the SuperCore Semaphore or
+   *  Mutex instance that provides the primary functionality of each
+   *  Classic API Semaphore instance.  The structure used is dependent
+   *  on the attributes specified by the user on the create directive.
+   *
+   *  @note Only one of these has meaning in a particular Classic API
+   *        Semaphore instance.
+   */
   union {
+    /**
+     *  This is the SuperCore Mutex instance associated with this Classic
+     *  API Semaphore instance.
+     */
     CORE_mutex_Control     mutex;
+
+    /**
+     *  This is the SuperCore Semaphore instance associated with this Classic
+     *  API Semaphore instance.
+     */
     CORE_semaphore_Control semaphore;
   } Core_control;
 }   Semaphore_Control;
diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h
index f2227957bb..f09b0eb329 100644
--- a/cpukit/rtems/include/rtems/rtems/tasks.h
+++ b/cpukit/rtems/include/rtems/rtems/tasks.h
@@ -182,13 +182,20 @@ typedef rtems_task ( *rtems_task_entry )(
  *  initialization time.
  */
 typedef struct {
-  rtems_name            name;              /* task name */
-  size_t                stack_size;        /* task stack size */
-  rtems_task_priority   initial_priority;  /* task priority */
-  rtems_attribute       attribute_set;     /* task attributes */
-  rtems_task_entry      entry_point;       /* task entry point */
-  rtems_mode            mode_set;          /* task initial mode */
-  rtems_task_argument	argument;          /* task argument */
+  /** This is the Initialization Task's name. */
+  rtems_name            name;
+  /** This is the Initialization Task's stack size. */
+  size_t                stack_size;
+  /** This is the Initialization Task's priority. */
+  rtems_task_priority   initial_priority;
+  /** This is the Initialization Task's attributes. */
+  rtems_attribute       attribute_set;
+  /** This is the Initialization Task's entry point. */
+  rtems_task_entry      entry_point;
+  /** This is the Initialization Task's initial mode. */
+  rtems_mode            mode_set;
+  /** This is the Initialization Task's argument. */
+  rtems_task_argument	argument;
 } rtems_initialization_tasks_table;
 
 /**
@@ -196,9 +203,13 @@ typedef struct {
  *  the RTEMS API to function correctly.
  */
 typedef struct {
+  /** This field contains the notepads for this task. */
   uint32_t                 Notepads[ RTEMS_NUMBER_NOTEPADS ];
+  /** This field contains the pending events for this task. */
   rtems_event_set          pending_events;
+  /** This field contains the event wait condition for this task. */
   rtems_event_set          event_condition;
+  /** This field contains the Classic API Signal information for this task. */
   ASR_Information          Signal;
 }  RTEMS_API_Control;
 
diff --git a/cpukit/rtems/include/rtems/rtems/timer.h b/cpukit/rtems/include/rtems/rtems/timer.h
index d474660af9..a7d6029620 100644
--- a/cpukit/rtems/include/rtems/rtems/timer.h
+++ b/cpukit/rtems/include/rtems/rtems/timer.h
@@ -67,10 +67,33 @@ extern "C" {
  *  may belong.
  */
 typedef enum {
+  /**
+   * This value indicates the timer is currently in use as an interval
+   * timer which will fire in the clock tick ISR.
+   */
   TIMER_INTERVAL,
+
+  /**
+   * This value indicates the timer is currently in use as an interval
+   * timer which will fire in the timer server task.
+   */
   TIMER_INTERVAL_ON_TASK,
+
+  /**
+   * This value indicates the timer is currently in use as an time of day
+   * timer which will fire in the clock tick ISR.
+   */
   TIMER_TIME_OF_DAY,
+
+  /**
+   * This value indicates the timer is currently in use as an time of day
+   * timer which will fire in the timer server task.
+   */
   TIMER_TIME_OF_DAY_ON_TASK,
+
+  /**
+   * This value indicates the timer is currently not in use.
+   */
   TIMER_DORMANT
 } Timer_Classes;
 
@@ -79,6 +102,11 @@ typedef enum {
  */
 typedef void rtems_timer_service_routine;
 
+/**
+ *  This type defines the type used to manage and indirectly invoke
+ *  Timer Service Routines (TSRs).  This defines the prototype and interface
+ *  for a function which is to be used as a TSR.
+ */
 typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )(
                  rtems_id,
                  void *
@@ -98,17 +126,29 @@ RTEMS_TIMER_EXTERN Objects_Information  _Timer_Information;
 RTEMS_TIMER_EXTERN Thread_Control *_Timer_Server;
 
 /**
- *  The following chains contain the list of interval timers that are
+ *  This chain contains the list of interval timers that are
  *  executed in the context of the Timer Server.
  *
- *  NOTE: These are extern'ed because they do not have to be in the
- *        minimum footprint.  They are only really required when
+ *  @note This is extern'ed because they do not have to be in the
+ *        minimum footprint.  It is only really required when
  *        task-based timers are used.  Since task-based timers can
- *        not be started until the server is initiated, these structures
- *        do not have to be initialized until then.  They are declared
+ *        not be started until the server is initiated, this structure
+ *        does not have to be initialized until then.  This is declared
  *        in the same file as _Timer_Server_body.
  */
 extern Chain_Control _Timer_Ticks_chain;
+
+/**
+ *  This chain contains the list of time of day timers that are
+ *  executed in the context of the Timer Server.
+ *
+ *  @note This is extern'ed because they do not have to be in the
+ *        minimum footprint.  It is only really required when
+ *        task-based timers are used.  Since task-based timers can
+ *        not be started until the server is initiated, this structure
+ *        does not have to be initialized until then.  This is declared
+ *        in the same file as _Timer_Server_body.
+ */
 extern Chain_Control _Timer_Seconds_chain;
 
 /**
@@ -116,8 +156,11 @@ extern Chain_Control _Timer_Seconds_chain;
  *  each timer.
  */
 typedef struct {
+  /** This field is the object management portion of a Timer instance. */
   Objects_Control  Object;
+  /** This field is the Watchdog instance which will be the scheduled. */
   Watchdog_Control Ticker;
+  /** This field indicates what type of timer this currently is. */
   Timer_Classes    the_class;
 }   Timer_Control;
 
@@ -288,9 +331,13 @@ rtems_status_code rtems_timer_initiate_server(
  *  service.
  */
 typedef struct {
+  /** This indicates the current type of the timer. */
   Timer_Classes      the_class;
+  /** This indicates the initial requested interval. */
   Watchdog_Interval  initial;
+  /** This indicates the time the timer was initially scheduled. */
   Watchdog_Interval  start_time;
+  /** This indicates the time the timer is scheduled to fire. */
   Watchdog_Interval  stop_time;
 } rtems_timer_information;
 
@@ -340,6 +387,10 @@ void _Timer_Server_process_ticks_chain(void);
  */
 void _Timer_Server_process_seconds_chain(void);
 
+/**
+ *  This method resets a timer and places it on the Ticks chain.  It
+ *  is assumed that the timer has already been canceled.
+ */
 #define _Timer_Server_reset_ticks_timer() \
    do { \
       if ( !_Chain_Is_empty( &_Timer_Ticks_chain ) ) { \
@@ -348,6 +399,10 @@ void _Timer_Server_process_seconds_chain(void);
       } \
    } while (0)
 
+/**
+ *  This method resets a timer and places it on the Seconds chain.  It
+ *  is assumed that the timer has already been canceled.
+ */
 #define _Timer_Server_reset_seconds_timer() \
    do { \
       if ( !_Chain_Is_empty( &_Timer_Seconds_chain ) ) { \
diff --git a/cpukit/rtems/include/rtems/rtems/types.h b/cpukit/rtems/include/rtems/rtems/types.h
index 7b5eb9e213..0eb53c30bb 100644
--- a/cpukit/rtems/include/rtems/rtems/types.h
+++ b/cpukit/rtems/include/rtems/rtems/types.h
@@ -44,28 +44,56 @@ extern "C" {
 #include <rtems/score/mppkt.h>
 #endif
 
-typedef single_precision rtems_single;    /* single precision float */
-typedef double_precision rtems_double;    /* double precision float */
+/** This type defines a single precision float. */
+typedef single_precision rtems_single;
 
+/** This type defines a double precision float. */
+typedef double_precision rtems_double;
+
+/** This type defines the RTEMS boolean type . */
 typedef boolean          rtems_boolean;
 
+/** This type defines is for Classic API object names. */
 typedef uint32_t         rtems_name;
 
+/**
+ *  This type defines is for RTEMS object Id.  Although this
+ *  type name is specific to the Classic API, the format of
+ *  an object Id is the same across all APIs.
+ */
 typedef Objects_Id       rtems_id;
 
+/**
+ *  This defines a value that is an invalid object Id.
+ */
 #define RTEMS_ID_NONE OBJECTS_ID_NONE
 
+/**
+ * This type is the public name for task context area.
+ */
 typedef Context_Control            rtems_context;
+
+/**
+ * This type is the public name for task floating point context area.
+ */
 typedef Context_Control_fp         rtems_context_fp;
+
+/**
+ * This type is the public name for the architecture specific
+ * stack frame built as part of vectoring an interrupt.
+ */
 typedef CPU_Interrupt_frame        rtems_interrupt_frame;
 
 /**
- *  Region information block
+ *  This type defines the public name for the information
+ *  structure returned by the Heap Handler via the Region
+ *  Manager.
  */
 typedef Heap_Information_block region_information_block;
 
 /**
- *  Time related
+ *  This type defines the public name for the type that is
+ *  used to manage intervals specified by clock ticks.
  */
 typedef Watchdog_Interval rtems_interval;
 
@@ -73,7 +101,7 @@ typedef Watchdog_Interval rtems_interval;
  *  The following record defines the time of control block.  This
  *  control block is used to maintain the current time of day.
  *
- *  @note This is an RTEID style time/date.
+ *  @note This is an RTEID (a.k.a. Classic API) style time/date.
  */
 typedef struct {
   /** This field is the year, A.D. */
@@ -93,7 +121,7 @@ typedef struct {
 }   rtems_time_of_day;
 
 /**
- *  Define the type for an RTEMS API task mode.
+ *  This defines the public name for an RTEMS API task mode type.
  */
 typedef Modes_Control rtems_mode;
 
@@ -101,18 +129,61 @@ typedef Modes_Control rtems_mode;
  *  MPCI related entries
  */
 #if defined(RTEMS_MULTIPROCESSING)
+/**
+ * This defines the public name for the set of MPCI packet
+ * classes which are internally dispatched to the managers.
+ */
 typedef MP_packet_Classes          rtems_mp_packet_classes;
+
+/**
+ * This defines the public name for the common prefix
+ * found at the beginning of each MPCI packet sent between
+ * nodes. This can be thought of as an envelope.
+ */
 typedef MP_packet_Prefix           rtems_packet_prefix;
 
+/**
+ * This defines the public name for the type for an indirect pointer
+ * to the initialization entry point for an MPCI handler.
+ */
 typedef MPCI_initialization_entry  rtems_mpci_initialization_entry;
+
+/**
+ * This defines the public name for the type for an indirect pointer
+ * to the get_packet entry point for an MPCI handler.
+ */
 typedef MPCI_get_packet_entry      rtems_mpci_get_packet_entry;
+
+/**
+ * This defines the public name for the type for an indirect pointer
+ * to the return_packet entry point for an MPCI handler.
+ */
 typedef MPCI_return_packet_entry   rtems_mpci_return_packet_entry;
+
+/**
+ * This defines the public name for the type for an indirect pointer
+ * to the send_packet entry point for an MPCI handler.
+ */
 typedef MPCI_send_entry            rtems_mpci_send_packet_entry;
+
+/**
+ * This defines the public name for the type for an indirect pointer
+ * to the receive entry point for an MPCI handler.
+ */
 typedef MPCI_receive_entry         rtems_mpci_receive_packet_entry;
 
-typedef MPCI_Entry rtems_mpci_entry;
+/**
+ * This defines the public name for the return type from every
+ * MPCI handler routine.
+ */
+typedef MPCI_Entry                 rtems_mpci_entry;
+
+/**
+ * This defines the public name for the structure which is used to
+ * configure an MPCI handler.
+ */
+typedef MPCI_Control               rtems_mpci_table;
 
-typedef MPCI_Control rtems_mpci_table;
 #endif
 
 #ifdef __cplusplus