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

	* rtems/include/rtems.h, rtems/include/rtems/rtems/ratemon.h,
	rtems/include/rtems/rtems/status.h,
	rtems/include/rtems/rtems/tasks.h, rtems/include/rtems/rtems/timer.h,
	rtems/inline/rtems/rtems/sem.inl: More Doxygen warnings removed.

7 files changed, 281 insertions, 48 deletions

diff --git a/cpukit/ChangeLog b/cpukit/ChangeLog
index 774972b377..92279765eb 100644
--- a/cpukit/ChangeLog
+++ b/cpukit/ChangeLog
@@ -1,3 +1,10 @@
+2008-04-28	Joel Sherrill <joel.sherrill@oarcorp.com>
+
+	* rtems/include/rtems.h, rtems/include/rtems/rtems/ratemon.h,
+	rtems/include/rtems/rtems/status.h,
+	rtems/include/rtems/rtems/tasks.h, rtems/include/rtems/rtems/timer.h,
+	rtems/inline/rtems/rtems/sem.inl: More Doxygen warnings removed.
+
 2008-04-28	Daron Chabot <daron.chabot@usask.ca>
 
 	* posix/src/keycreate.c, posix/src/pthreadequal.c,
diff --git a/cpukit/rtems/include/rtems.h b/cpukit/rtems/include/rtems.h
index e4441ec069..49cf5f76e0 100644
--- a/cpukit/rtems/include/rtems.h
+++ b/cpukit/rtems/include/rtems.h
@@ -31,7 +31,11 @@
 extern "C" {
 #endif
 
-/*
+#if (!defined(__RTEMS_VIOLATE_KERNEL_VISIBILITY__)) && \
+    (!defined(__RTEMS_INSIDE__))
+/**
+ *  @brief Compiling RTEMS Application Macro
+ *
  *  Unless told otherwise, the RTEMS include files will hide some stuff
  *  from normal application code.  Defining this crosses a boundary which
  *  is undesirable since it means your application is using RTEMS features
@@ -39,7 +43,6 @@ extern "C" {
  *  Define this at your own risk.
  */
 
-#if (!defined(__RTEMS_VIOLATE_KERNEL_VISIBILITY__)) && (!defined(__RTEMS_INSIDE__))
 #define __RTEMS_APPLICATION__
 #endif
 
@@ -76,23 +79,72 @@ extern "C" {
 #include <rtems/rtems/support.h>
 #include <rtems/score/sysstate.h>
 
+/**
+ *  This constant indicates whether this processor variant has
+ *  hardware floating point support.
+ */
 #define RTEMS_HAS_HARDWARE_FP CPU_HARDWARE_FP
 
-/**
+/*
  *  The following define the constants which may be used in name searches.
  */
+
+/**
+ * This constant indicates that the search is across all nodes.
+ */
 #define RTEMS_SEARCH_ALL_NODES   OBJECTS_SEARCH_ALL_NODES
+
+/**
+ *  This constant indicates that the search is across all nodes
+ *  except the one the call is made from.
+ */
 #define RTEMS_SEARCH_OTHER_NODES OBJECTS_SEARCH_OTHER_NODES
+
+/**
+ *  This constant indicates that the search is to be restricted
+ *  to the local node.
+ */
 #define RTEMS_SEARCH_LOCAL_NODE  OBJECTS_SEARCH_LOCAL_NODE
-#define RTEMS_WHO_AM_I           OBJECTS_WHO_AM_I
 
 /**
+ *  This constant indicates that the caller wants to obtain the
+ *  name of the currently executing thread.
+ *
+ *  @note This constant is only meaningful when obtaining the name
+ *        of a task.
+ */
+#define RTEMS_WHO_AM_I           OBJECTS_WHO_AM_I
+
+/*
  * Parameters and return id's for _Objects_Get_next
  */
+
+/**
+ *  This constant is the lowest valid valid for the index portion
+ *  of an object Id.
+ */
 #define RTEMS_OBJECT_ID_INITIAL_INDEX        OBJECTS_ID_INITIAL_INDEX
+
+/**
+ *  This constant is the maximum valid valid for the index portion
+ *  of an object Id.
+ */
 #define RTEMS_OBJECT_ID_FINAL_INDEX          OBJECTS_ID_FINAL_INDEX
-#define RTEMS_OBJECT_ID_INITIAL(api, class, node) OBJECTS_ID_INITIAL(api, class, node)
 
+/**
+ *  This method returns the Id of the object with the lowest
+ *  valid index valud.
+ *
+ *  @param[in] _api is the API of the object
+ *  @param[in] _class is the Object Class of the object
+ *  @param[in] _node is the node where the object resides
+ */
+#define RTEMS_OBJECT_ID_INITIAL(_api, _class, _node) \
+   OBJECTS_ID_INITIAL(_api, _class, _node)
+
+/**
+ *  This constant is the maximum valid object Id.
+ */
 #define RTEMS_OBJECT_ID_FINAL                OBJECTS_ID_FINAL
 
 /**
diff --git a/cpukit/rtems/include/rtems/rtems/ratemon.h b/cpukit/rtems/include/rtems/rtems/ratemon.h
index 56c5f7d6a3..038c26e31e 100644
--- a/cpukit/rtems/include/rtems/rtems/ratemon.h
+++ b/cpukit/rtems/include/rtems/rtems/ratemon.h
@@ -158,7 +158,13 @@ typedef struct {
   Thread_Control                         *owner;
   rtems_rate_monotonic_period_statistics  Statistics;
 }   Rate_monotonic_Control;
-
+ 
+/**
+ *  @brief Rate Monotonic Period Class Management Structure
+ *
+ *  This instance of Objects_Information is used to manage the
+ *  set of rate monotonic period instances.
+ */
 RTEMS_RATEMON_EXTERN Objects_Information _Rate_monotonic_Information;
 
 /**
@@ -320,6 +326,11 @@ void _Rate_monotonic_Timeout(
   #define _Rate_monotonic_Reset_wall_time_statistics( _the_period )
 #endif
 
+/**
+ *  @brief Rate_monotonic_Reset_cpu_use_statistics
+ *
+ *  This helper method resets the period CPU usage statistics structure.
+ */
 #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS
   #define _Rate_monotonic_Reset_cpu_use_statistics( _the_period ) \
      do { \
@@ -331,6 +342,11 @@ void _Rate_monotonic_Timeout(
   #define _Rate_monotonic_Reset_cpu_use_statistics( _the_period )
 #endif
 
+/**
+ *  @brief Rate_monotonic_Reset_statistics
+ *
+ *  This helper method resets the period wall time statistics structure.
+ */
 #define _Rate_monotonic_Reset_statistics( _the_period ) \
   do { \
     memset( \
diff --git a/cpukit/rtems/include/rtems/rtems/status.h b/cpukit/rtems/include/rtems/rtems/status.h
index 5a50941136..d32b433842 100644
--- a/cpukit/rtems/include/rtems/rtems/status.h
+++ b/cpukit/rtems/include/rtems/rtems/status.h
@@ -29,55 +29,178 @@
 extern "C" {
 #endif
 
-/* types */
-
-/* enumerated constants */
-
+/**
+ *  @brief Classic API Status
+ *
+ *  This enumerates the possible status values returned b
+ *  Classic API directives.
+ */
 typedef enum {
-  RTEMS_SUCCESSFUL               =  0, /* successful completion */
-  RTEMS_TASK_EXITTED             =  1, /* returned from a thread */
-  RTEMS_MP_NOT_CONFIGURED        =  2, /* multiprocessing not configured */
-  RTEMS_INVALID_NAME             =  3, /* invalid object name */
-  RTEMS_INVALID_ID               =  4, /* invalid object id */
-  RTEMS_TOO_MANY                 =  5, /* too many */
-  RTEMS_TIMEOUT                  =  6, /* timed out waiting */
-  RTEMS_OBJECT_WAS_DELETED       =  7, /* object deleted while waiting */
-  RTEMS_INVALID_SIZE             =  8, /* specified size was invalid */
-  RTEMS_INVALID_ADDRESS          =  9, /* address specified is invalid */
-  RTEMS_INVALID_NUMBER           = 10, /* number was invalid */
-  RTEMS_NOT_DEFINED              = 11, /* item has not been initialized */
-  RTEMS_RESOURCE_IN_USE          = 12, /* resources still outstanding */
-  RTEMS_UNSATISFIED              = 13, /* request not satisfied */
-  RTEMS_INCORRECT_STATE          = 14, /* thread is in wrong state */
-  RTEMS_ALREADY_SUSPENDED        = 15, /* thread already in state */
-  RTEMS_ILLEGAL_ON_SELF          = 16, /* illegal on calling thread */
-  RTEMS_ILLEGAL_ON_REMOTE_OBJECT = 17, /* illegal for remote object */
-  RTEMS_CALLED_FROM_ISR          = 18, /* called from wrong environment */
-  RTEMS_INVALID_PRIORITY         = 19, /* invalid thread priority */
-  RTEMS_INVALID_CLOCK            = 20, /* invalid date/time */
-  RTEMS_INVALID_NODE             = 21, /* invalid node id */
-  RTEMS_NOT_CONFIGURED           = 22, /* directive not configured */
-  RTEMS_NOT_OWNER_OF_RESOURCE    = 23, /* not owner of resource */
-  RTEMS_NOT_IMPLEMENTED          = 24, /* directive not implemented */
-  RTEMS_INTERNAL_ERROR           = 25, /* RTEMS inconsistency detected */
-  RTEMS_NO_MEMORY                = 26, /* could not get enough memory */
-  RTEMS_IO_ERROR                 = 27, /* driver IO error */
-  RTEMS_PROXY_BLOCKING           = 28  /* internal error only */
+  /**
+   *  This is the status to indicate successful completion.
+   */
+  RTEMS_SUCCESSFUL               =  0,
+  /**
+   *  This is the status to indicate that a thread exited.
+   */
+  RTEMS_TASK_EXITTED             =  1,
+  /**
+   *  This is the status to indicate multiprocessing is not configured.
+   */
+  RTEMS_MP_NOT_CONFIGURED        =  2,
+  /**
+   *  This is the status to indicate that the object name was invalid.
+   */
+  RTEMS_INVALID_NAME             =  3,
+  /**
+   *  This is the status to indicate that the object Id was invalid.
+   */
+  RTEMS_INVALID_ID               =  4,
+  /**
+   *  This is the status to indicate you have attempted to create too many
+   *  instances of a particular object class.
+   */
+  RTEMS_TOO_MANY                 =  5,
+  /**
+   *  This is the status to indicate that a blocking directive timed out.
+   */
+  RTEMS_TIMEOUT                  =  6,
+  /**
+   *  This is the status to indicate the the object was deleted
+   *  while the task was blocked waiting.
+   */
+  RTEMS_OBJECT_WAS_DELETED       =  7,
+  /**
+   *  This is the status to indicate that the specified size was invalid.
+   */
+  RTEMS_INVALID_SIZE             =  8,
+  /**
+   *  This is the status to indicate that the specified address is invalid.
+   */
+  RTEMS_INVALID_ADDRESS          =  9,
+  /**
+   *  This is the status to indicate that the specified number was invalid.
+   */
+  RTEMS_INVALID_NUMBER           = 10,
+  /**
+   *  This is the status to indicate that the item has not been initialized.
+   */
+  RTEMS_NOT_DEFINED              = 11,
+  /**
+   *  This is the status to indicate that the object still has
+   *  resources in use.
+   */
+  RTEMS_RESOURCE_IN_USE          = 12,
+  /**
+   *  This is the status to indicate that the request was not satisfied.
+   */
+  RTEMS_UNSATISFIED              = 13,
+  /**
+   *  This is the status to indicate that a thread is in wrong state
+   *  was in the wrong execution state for the requested operation.
+   */
+  RTEMS_INCORRECT_STATE          = 14,
+  /**
+   *  This is the status to indicate thread was already suspended.
+   */
+  RTEMS_ALREADY_SUSPENDED        = 15,
+  /**
+   *  This is the status to indicate that the operation is illegal
+   *  on calling thread.
+   */
+  RTEMS_ILLEGAL_ON_SELF          = 16,
+  /**
+   *  This is the status to indicate illegal for remote object.
+   */
+  RTEMS_ILLEGAL_ON_REMOTE_OBJECT = 17,
+  /**
+   *  This is the status to indicate that the operation should not be
+   *  called from from this excecution environment.
+   */
+  RTEMS_CALLED_FROM_ISR          = 18,
+  /**
+   *  This is the status to indicate that an invalid thread priority
+   *  was provided.
+   */
+  RTEMS_INVALID_PRIORITY         = 19,
+  /**
+   *  This is the status to indicate that the specified date/time was invalid.
+   */
+  RTEMS_INVALID_CLOCK            = 20,
+  /**
+   *  This is the status to indicate that the specified node Id was invalid.
+   */
+  RTEMS_INVALID_NODE             = 21,
+  /**
+   *  This is the status to indicate that the directive was not configured.
+   */
+  RTEMS_NOT_CONFIGURED           = 22,
+  /**
+   *  This is the status to indicate that the caller is not the
+   *  owner of the resource.
+   */
+  RTEMS_NOT_OWNER_OF_RESOURCE    = 23,
+  /**
+   *  This is the status to indicate the the directive or requested
+   *  portion of the directive is not implemented.  This is a hint
+   *  that you have stumbled across an opportunity to submit code
+   *  to the RTEMS Project.
+   */
+  RTEMS_NOT_IMPLEMENTED          = 24,
+  /**
+   *  This is the status to indicate that an internal RTEMS inconsistency
+   *  was detected.
+   */
+  RTEMS_INTERNAL_ERROR           = 25,
+  /**
+   *  This is the status to indicate that the directive attempted to allocate
+   *  memory but was unable to do so.
+   */
+  RTEMS_NO_MEMORY                = 26,
+  /**
+   *  This is the status to indicate an driver IO error.
+   */
+  RTEMS_IO_ERROR                 = 27,
+  /**
+   *  This is the status is used internally to RTEMS when performing
+   *  operations on behalf of remote tasks.  This is referred to as
+   *  proxying operations and this status indicates that the operation
+   *  could not be completed immediately and the "proxy is blocking."
+   *
+   *  @note This status will @b NOT be returned to the user.
+   */
+  RTEMS_PROXY_BLOCKING           = 28,
 } rtems_status_code;
 
+/**
+ *  This is the lowest valid value for a Classic API status code.
+ */
 #define RTEMS_STATUS_CODES_FIRST RTEMS_SUCCESSFUL
-#define RTEMS_STATUS_CODES_LAST  RTEMS_PROXY_BLOCKING
 
-extern rtems_status_code _Status_Object_name_errors_to_status[];
+/**
+ *  This is the highest valid value for a Classic API status code.
+ */
+#define RTEMS_STATUS_CODES_LAST  RTEMS_PROXY_BLOCKING
 
+/**
+ *  This array is used to map SuperCore Object Handler return
+ *  codes to Classic API status codes.
+ */
 #ifdef RTEMS_API_INIT
 rtems_status_code _Status_Object_name_errors_to_status[] = {
-  RTEMS_SUCCESSFUL,      /* OBJECTS_SUCCESSFUL */
-  RTEMS_INVALID_NAME,    /* OBJECTS_INVALID_NAME */
-  RTEMS_INVALID_ADDRESS, /* OBJECTS_INVALID_ADDRESS */
-  RTEMS_INVALID_ID,      /* OBJECTS_INVALID_ID */
-  RTEMS_INVALID_NODE     /* OBJECTS_INVALID_NODE */
+  /** This maps OBJECTS_SUCCESSFUL to RTEMS_SUCCESSFUL. */
+  RTEMS_SUCCESSFUL,
+  /** This maps OBJECTS_INVALID_NAME to RTEMS_INVALID_NAME. */
+  RTEMS_INVALID_NAME,
+  /** This maps OBJECTS_INVALID_ADDRESS to RTEMS_INVALID_NAME. */
+  RTEMS_INVALID_ADDRESS,
+  /** This maps OBJECTS_INVALID_ID to RTEMS_INVALID_ADDRESS. */
+  RTEMS_INVALID_ID,
+  /** This maps OBJECTS_INVALID_NODE to RTEMS_INVALID_NODE. */
+  RTEMS_INVALID_NODE
 };
+#else
+extern rtems_status_code _Status_Object_name_errors_to_status[];
 #endif
 
 /*
diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h
index d10ac03853..f2227957bb 100644
--- a/cpukit/rtems/include/rtems/rtems/tasks.h
+++ b/cpukit/rtems/include/rtems/rtems/tasks.h
@@ -81,9 +81,30 @@ extern "C" {
  */
 typedef Priority_Control rtems_task_priority;
 
+/**
+ *  This is the constant used with the rtems_task_set_priority
+ *  directive to indicate that the caller wants to obtain its
+ *  current priority rather than set it as the name of the
+ *  directive indicates.
+ */
 #define RTEMS_NO_PRIORITY           RTEMS_CURRENT_PRIORITY
 
+/**
+ *  This constant is the least valid value for a Classic API
+ *  task priority.
+ */
 #define RTEMS_MINIMUM_PRIORITY      (PRIORITY_MINIMUM + 1)
+
+/**
+ *  This constant is the maximum valid value for a Classic API
+ *  task priority.
+ *
+ *  @note This is actually the priority of the IDLE thread so
+ *        using this priority will result in having a task
+ *        which never executes.  This could be useful if you
+ *        want to ensure that a task does not executes during
+ *        certain operations such as a system mode change.
+ */
 #define RTEMS_MAXIMUM_PRIORITY      PRIORITY_MAXIMUM
 
 /**
@@ -129,6 +150,7 @@ typedef Priority_Control rtems_task_priority;
 /** This is used to indicate the highest numbered notepad. */
 #define RTEMS_NOTEPAD_LAST RTEMS_NOTEPAD_15
 
+/** This is used to indicate the number of notepads available. */
 #define RTEMS_NUMBER_NOTEPADS  (RTEMS_NOTEPAD_LAST+1)
 
 /**
@@ -180,8 +202,8 @@ typedef struct {
   ASR_Information          Signal;
 }  RTEMS_API_Control;
 
-/*
- *  The following defines the information control block used to
+/**
+ *  The following instantiates the information control block used to
  *  manage this class of objects.
  */
 RTEMS_TASKS_EXTERN Objects_Information _RTEMS_tasks_Information;
diff --git a/cpukit/rtems/include/rtems/rtems/timer.h b/cpukit/rtems/include/rtems/rtems/timer.h
index 1fbe458da9..e1e0b7c0bc 100644
--- a/cpukit/rtems/include/rtems/rtems/timer.h
+++ b/cpukit/rtems/include/rtems/rtems/timer.h
@@ -312,6 +312,8 @@ rtems_status_code rtems_timer_get_information(
  */
 extern Watchdog_Control _Timer_Seconds_timer;
 
+/**
+ *  This method is used to temporaril
 #define _Timer_Server_stop_ticks_timer() \
       _Watchdog_Remove( &_Timer_Server->Timer )
 
diff --git a/cpukit/rtems/inline/rtems/rtems/sem.inl b/cpukit/rtems/inline/rtems/rtems/sem.inl
index 01058d2257..566c823f81 100644
--- a/cpukit/rtems/inline/rtems/rtems/sem.inl
+++ b/cpukit/rtems/inline/rtems/rtems/sem.inl
@@ -67,6 +67,17 @@ RTEMS_INLINE_ROUTINE Semaphore_Control *_Semaphore_Get (
     _Objects_Get( &_Semaphore_Information, id, location );
 }
 
+/**
+ *  @brief Semaphore_Get (Interrupts disabled)
+ *
+ *  This function maps semaphore IDs to semaphore control blocks.
+ *  If ID corresponds to a local semaphore, then it returns
+ *  the_semaphore control pointer which maps to ID and location
+ *  is set to OBJECTS_LOCAL.  if the semaphore ID is global and
+ *  resides on a remote node, then location is set to OBJECTS_REMOTE,
+ *  and the_semaphore is undefined.  Otherwise, location is set
+ *  to OBJECTS_ERROR and the_semaphore is undefined.
+ */
 RTEMS_INLINE_ROUTINE Semaphore_Control *_Semaphore_Get_interrupt_disable (
   Objects_Id         id,
   Objects_Locations *location,