2009-08-06 Christian Mauderer <christian.mauderer@embedded-brains.de>

        * rtems/include/rtems/rtems/types.h: Improve documentation.

1 files changed, 85 insertions, 64 deletions

diff --git a/cpukit/rtems/include/rtems/rtems/types.h b/cpukit/rtems/include/rtems/rtems/types.h
index 4cd4dd5a0d..4c867c5cf4 100644
--- a/cpukit/rtems/include/rtems/rtems/types.h
+++ b/cpukit/rtems/include/rtems/rtems/types.h
@@ -1,7 +1,9 @@
 /**
- * @file rtems/rtems/types.h
+ * @file
  *
- *  This include file defines the types used by the RTEMS API.
+ * @ingroup ClassicRTEMS
+ *
+ * @brief Types used by the Classic API.
  */
 
 /*  COPYRIGHT (c) 1989-2008.
@@ -17,15 +19,6 @@
 #ifndef _RTEMS_RTEMS_TYPES_H
 #define _RTEMS_RTEMS_TYPES_H
 
-/**
- *  @defgroup ClassicTypes Types
- *
- *  @ingroup ClassicRTEMS
- *
- *  This encapsulates functionality which XXX
- */
-/**@{*/
-
 /*
  *  RTEMS basic type definitions
  */
@@ -46,68 +39,92 @@
 extern "C" {
 #endif
 
-/** This type defines a single precision float. */
+/**
+ * @addtogroup ClassicRTEMS
+ *
+ * @{
+ */
+
 #ifdef RTEMS_DEPRECATED_TYPES
+/**
+ * @brief Single precision float type.
+ *
+ * @deprecated Use @c float instead.
+ */
 typedef single_precision rtems_single;
 
-/** This type defines a double precision float. */
+/**
+ * @brief Double precision float type.
+ *
+ * @deprecated Use @c double instead.
+ */
 typedef double_precision rtems_double;
 
-/** This type defines the RTEMS boolean type . */
+/**
+ * @brief RTEMS boolean type.
+ *
+ * @deprecated Use @c bool instead
+ */
 typedef boolean          rtems_boolean;
 #endif
 
-/** This type defines is for Classic API object names. */
+/**
+ * @brief Classic API object name Type.
+ *
+ * Contains the name of a Classic API object. It is an unsigned 32 bit integer
+ * which can be treated as a numeric value or initialized using
+ * rtems_build_name() to contain four ASCII characters.
+ */
 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.
+ * @brief Used to manage and manipulate RTEMS object identifier.
  */
 typedef Objects_Id       rtems_id;
 
 /**
- *  This defines a value that is an invalid object Id.
+ * @brief Invalid object identifier value.
+ *
+ * No object can have this identifier value.
  */
 #define RTEMS_ID_NONE OBJECTS_ID_NONE
 
 /**
- * This type is the public name for task context area.
+ * @brief Public name for task context area.
  */
 typedef Context_Control            rtems_context;
 
 #if (CPU_HARDWARE_FP == TRUE) || (CPU_SOFTWARE_FP == TRUE)
 /**
- * This type is the public name for task floating point context area.
+ * @brief Public name for task floating point context area.
  */
 typedef Context_Control_fp         rtems_context_fp;
 #endif
 
 /**
- * This type is the public name for the architecture specific
- * stack frame built as part of vectoring an interrupt.
+ * @brief Defines the format of the interrupt stack frame as it appears to a
+ * user ISR.
+ *
+ * This data structure may not be defined on all ports
  */
 typedef CPU_Interrupt_frame        rtems_interrupt_frame;
 
 /**
- *  This type defines the public name for the information
- *  structure returned by the Heap Handler via the Region
- *  Manager.
+ * @brief Information structure returned by the Heap Handler via the Region
+ * Manager.
  */
 typedef Heap_Information_block region_information_block;
 
 /**
- *  This type defines the public name for the type that is
- *  used to manage intervals specified by clock ticks.
+ * @brief Used to manage and manipulate intervals specified by clock ticks.
  */
 typedef Watchdog_Interval rtems_interval;
 
 /**
- *  This is the public type used to represent the CPU usage per thread.
+ * @brief Represents the CPU usage per thread.
  *
- *  @note When using nanosecond granularity timing, RTEMS may internally
- *        use a variety of represenations.
+ * When using nano seconds granularity timing, RTEMS may internally use a
+ * variety of represenations.
  */
 #ifndef __RTEMS_USE_TICKS_CPU_USAGE_STATISTICS__
   typedef struct timespec rtems_thread_cpu_usage_t;
@@ -117,30 +134,41 @@ 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 (a.k.a. Classic API) style time/date.
+ * @brief Data structure to manage and manipulate calendar time.
  */
 typedef struct {
-  /** This field is the year, A.D. */
+  /**
+   * @brief Year, A.D.
+   */
   uint32_t   year;
-  /** This field is the month, 1 -> 12 */
+  /**
+   * @brief Month, 1 .. 12.
+   */
   uint32_t   month;
-  /** This field is the day, 1 -> 31 */
+  /**
+   * @brief Day, 1 .. 31.
+   */
   uint32_t   day;
-  /** This field is the hour, 0 -> 23 */
+  /**
+   * @brief Hour, 0 .. 23.
+   */
   uint32_t   hour;
-  /** This field is the minute, 0 -> 59 */
+  /**
+   * @brief Minute, 0 .. 59.
+   */
   uint32_t   minute;
-  /** This field is the second, 0 -> 59 */
+  /**
+   * @brief Second, 0 .. 59.
+   */
   uint32_t   second;
-  /** This field is the elapsed ticks between secs */
+  /**
+   * @brief Elapsed ticks between seconds.
+   */
   uint32_t   ticks;
 }   rtems_time_of_day;
 
 /**
- *  This defines the public name for an RTEMS API task mode type.
+ * @brief Task mode type.
  */
 typedef Modes_Control rtems_mode;
 
@@ -149,67 +177,60 @@ typedef Modes_Control rtems_mode;
  */
 #if defined(RTEMS_MULTIPROCESSING)
 /**
- * This defines the public name for the set of MPCI packet
- * classes which are internally dispatched to the managers.
+ * @brief 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.
+ * @brief Prefix found at the beginning of each MPCI packet sent between nodes.
  */
 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.
+ * @brief 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.
+ * @brief 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.
+ * @brief 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.
+ * @brief 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.
+ * @brief Indirect pointer to the receive entry point for an MPCI handler.
  */
 typedef MPCI_receive_entry         rtems_mpci_receive_packet_entry;
 
 /**
- * This defines the public name for the return type from every
- * MPCI handler routine.
+ * @brief 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.
+ * @brief Structure which is used to configure an MPCI handler.
  */
 typedef MPCI_Control               rtems_mpci_table;
 
 #endif
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/**@}*/
-
 #endif
 /* end of include file */