2010-08-09 Sebastian Huber <sebastian.huber@embedded-brains.de>

	* rtems/include/rtems.h, rtems/mainpage.h,
	rtems/include/rtems/rtems/types.h: Documentation.

2 files changed, 25 insertions, 5 deletions

diff --git a/cpukit/rtems/include/rtems.h b/cpukit/rtems/include/rtems.h
index 4b759edce2..17b1ce0394 100644
--- a/cpukit/rtems/include/rtems.h
+++ b/cpukit/rtems/include/rtems.h
@@ -150,12 +150,29 @@ const char *rtems_get_version_string(void);
 
 /**
  * @brief Minimum stack size which every thread must exceed.
+ *
+ * It is the minimum stack size recommended for use on this processor. This
+ * value is selected by the RTEMS developers conservatively to minimize the
+ * risk of blown stacks for most user applications. Using this constant when
+ * specifying the task stack size, indicates that the stack size will be at
+ * least RTEMS_MINIMUM_STACK_SIZE bytes in size. If the user configured minimum
+ * stack size is larger than the recommended minimum, then it will be used. 
  */
 #define RTEMS_MINIMUM_STACK_SIZE  STACK_MINIMUM_SIZE
 
 /**
  * @brief Specifies that the task should be created with the configured minimum
  * stack size.
+ *
+ * Using this constant when specifying the task stack size indicates that this
+ * task is to be created with a stack size of the minimum stack size that was
+ * configured by the application. If not explicitly configured by the
+ * application, the default configured minimum stack size is the processor
+ * dependent value RTEMS_MINIMUM_STACK_SIZE. Since this uses the configured
+ * minimum stack size value, you may get a stack size that is smaller or larger
+ * than the recommended minimum. This can be used to provide large stacks for
+ * all tasks on complex applications or small stacks on applications that are
+ * trying to conserve memory. 
  */
 #define RTEMS_CONFIGURED_MINIMUM_STACK_SIZE  0
 
diff --git a/cpukit/rtems/include/rtems/rtems/types.h b/cpukit/rtems/include/rtems/rtems/types.h
index eecc019e68..2ceeeaa203 100644
--- a/cpukit/rtems/include/rtems/rtems/types.h
+++ b/cpukit/rtems/include/rtems/rtems/types.h
@@ -69,16 +69,17 @@ typedef boolean          rtems_boolean;
 #endif
 
 /**
- * @brief Classic API object name Type.
+ * @brief Classic API @ref ClassicRTEMSSubSecObjectNames "object name" type.
  *
- * Contains the name of a Classic API object. It is an unsigned 32 bit integer
+ * 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;
 
 /**
- * @brief Used to manage and manipulate RTEMS object identifier.
+ * @brief Used to manage and manipulate
+ * @ref ClassicRTEMSSubSecObjectIdentifiers "RTEMS object identifiers".
  */
 typedef Objects_Id       rtems_id;
 
@@ -116,7 +117,8 @@ typedef CPU_Interrupt_frame        rtems_interrupt_frame;
 typedef Heap_Information_block region_information_block;
 
 /**
- * @brief Used to manage and manipulate intervals specified by clock ticks.
+ * @brief Used to manage and manipulate intervals specified by
+ * @ref ClassicRTEMSSecTime "clock ticks".
  */
 typedef Watchdog_Interval rtems_interval;
 
@@ -133,7 +135,8 @@ typedef Watchdog_Interval rtems_interval;
 #endif
 
 /**
- * @brief Data structure to manage and manipulate calendar time.
+ * @brief Data structure to manage and manipulate calendar
+ * @ref ClassicRTEMSSecTime "time".
  */
 typedef struct {
   /**