rtems misc: Clean up Doxygen GCI Task #4

http://www.google-melange.com/gci/task/view/google/gci2012/7950205

10 files changed, 78 insertions, 25 deletions

diff --git a/cpukit/rtems/include/rtems/rtems/dpmem.h b/cpukit/rtems/include/rtems/rtems/dpmem.h
index 4869dee6c0..a4cf2517ce 100644
--- a/cpukit/rtems/include/rtems/rtems/dpmem.h
+++ b/cpukit/rtems/include/rtems/rtems/dpmem.h
@@ -77,7 +77,7 @@ typedef struct {
 RTEMS_DPMEM_EXTERN Objects_Information  _Dual_ported_memory_Information;
 
 /**
- *  @brief _Dual_ported_memory_Manager_initialization
+ *  @brief Dual Ported Memory Manager Initialization
  *
  *  This routine performs the initialization necessary for this manager.
  */
diff --git a/cpukit/rtems/include/rtems/rtems/event.h b/cpukit/rtems/include/rtems/rtems/event.h
index 8386c43e15..b3762b2bf8 100644
--- a/cpukit/rtems/include/rtems/rtems/event.h
+++ b/cpukit/rtems/include/rtems/rtems/event.h
@@ -469,6 +469,9 @@ void _Event_Surrender(
   States_Control                    wait_state
 );
 
+/**
+ *  @brief Timeout Event
+ */
 void _Event_Timeout(
   Objects_Id  id,
   void       *arg
diff --git a/cpukit/rtems/include/rtems/rtems/message.h b/cpukit/rtems/include/rtems/rtems/message.h
index fa80862fb3..9990b146da 100644
--- a/cpukit/rtems/include/rtems/rtems/message.h
+++ b/cpukit/rtems/include/rtems/rtems/message.h
@@ -97,21 +97,32 @@ typedef struct {
 RTEMS_MESSAGE_EXTERN Objects_Information  _Message_queue_Information;
 
 /**
- *  @brief Message_queue_Manager_initialization
+ *  @brief Message Queue Manager Initialization
  *
  *  This routine performs the initialization necessary for this manager.
  */
 void _Message_queue_Manager_initialization(void);
 
 /**
- *  @brief rtems_message_queue_create
+ *  @brief RTEMS Create Message Queue
  *
  *  This routine implements the rtems_message_queue_create directive.  The
- *  message queue will have the name name.  If the attribute_set indicates
+ *  message queue will have the @a name.  If the @a attribute_set indicates
  *  that the message queue is to be limited in the number of messages
- *  that can be outstanding, then count indicates the maximum number of
+ *  that can be outstanding, then @a count indicates the maximum number of
  *  messages that will be held.  It returns the id of the created
- *  message queue in ID.
+ *  message queue in @a id.
+ * 
+ *  @param[in] name is the user defined queue name
+ *  @param[in] count is the maximum message and reserved buffer count
+ *  @param[in] max_message_size is the maximum size of each message
+ *  @param[in] attribute_set is the process method
+ *  @param[in] id is the pointer to queue
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.  If successful, the @a id will
+ *          be filled in with the queue id.
  */
 rtems_status_code rtems_message_queue_create(
   rtems_name       name,
@@ -296,10 +307,14 @@ rtems_status_code _Message_queue_Submit(
 Message_queue_Control *_Message_queue_Allocate (void);
 
 /**
- *  @brief Message_queue_Translate_core_message_queue_return_code
+ *  @brief Message queue Translate Core Message Queue Return Code
  *
- *  This function returns a RTEMS status code based on the core message queue
- *  status code specified.
+ *  This function returns a RTEMS status code based on
+ *  @a the_message_queue_status.
+ * 
+ *  @param[in] the_message_queue_status is the status code to translate
+ * 
+ *  @return translated RTEMS status code
  */
 rtems_status_code _Message_queue_Translate_core_message_queue_return_code (
   uint32_t   the_message_queue_status
diff --git a/cpukit/rtems/include/rtems/rtems/object.h b/cpukit/rtems/include/rtems/rtems/object.h
index ced287f8b7..d8c1aa16f5 100644
--- a/cpukit/rtems/include/rtems/rtems/object.h
+++ b/cpukit/rtems/include/rtems/rtems/object.h
@@ -167,7 +167,7 @@ rtems_status_code rtems_object_set_name(
 /**
  *  @brief Get Class Portion of Object Id
  *
- *  This function returns the class portion of the ID.
+ *  This function returns the class portion of the @a _id ID.
  *
  *  @param[in] _id is the Id of the object to obtain the class from
  *
@@ -327,7 +327,7 @@ const char *rtems_object_get_api_class_name(
 );
 
 /**
- *  @brief Get Class Name
+ *  @brief Get Class Information
  *
  *  This method returns a string containing the name of the
  *  @a the_class from the specified @a api.
diff --git a/cpukit/rtems/include/rtems/rtems/region.h b/cpukit/rtems/include/rtems/rtems/region.h
index 61162cbb99..055e25d570 100644
--- a/cpukit/rtems/include/rtems/rtems/region.h
+++ b/cpukit/rtems/include/rtems/rtems/region.h
@@ -176,15 +176,26 @@ rtems_status_code rtems_region_delete(
 );
 
 /**
- *  @brief rtems_region_get_segment
+ *  @brief RTEMS Get Region Segment
  *
  *  This routine implements the rtems_region_get_segment directive.  It
- *  attempts to allocate a segment from the region associated with ID.
- *  If a segment of the requested size can be allocated, its address
- *  is returned in segment.  If no segment is available, then the task
+ *  attempts to allocate a segment from the region associated with @a id.
+ *  If a segment of the requested @a size size can be allocated, its address
+ *  is returned in @a segment.  If no segment is available, then the task
  *  may return immediately or block waiting for a segment with an optional
- *  timeout of timeout clock ticks.  Whether the task blocks or returns
- *  immediately is based on the no_wait option in the option_set.
+ *  timeout of @a timeout clock ticks.  Whether the task blocks or returns
+ *  immediately is based on the no_wait option in the @a option_set.
+ * 
+ *  @param[in] id is the region id
+ *  @param[in] size is the segment size in bytes
+ *  @param[in] option_set is the wait option
+ *  @param[in] timeout is the number of ticks to wait (0 means wait forever)
+ *  @param[in] segment is the pointer to segment address
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.  If successful, the segment will
+ *          be filled in with the segment address. 
  */
 rtems_status_code rtems_region_get_segment(
   rtems_id           id,
diff --git a/cpukit/rtems/include/rtems/rtems/sem.h b/cpukit/rtems/include/rtems/rtems/sem.h
index a75ef4130a..23220887d0 100644
--- a/cpukit/rtems/include/rtems/rtems/sem.h
+++ b/cpukit/rtems/include/rtems/rtems/sem.h
@@ -104,7 +104,7 @@ typedef struct {
 RTEMS_SEM_EXTERN Objects_Information  _Semaphore_Information;
 
 /**
- *  @brief Semaphore_Manager_initialization
+ *  @brief Semaphore Manager Initialization
  *
  *  This routine performs the initialization necessary for this manager.
  */
@@ -152,10 +152,16 @@ rtems_status_code rtems_semaphore_ident(
 );
 
 /**
- *  @brief rtems_semaphore_delete
+ *  @brief RTEMS Delete Semaphore
  *
  *  This routine implements the rtems_semaphore_delete directive.  The
  *  semaphore indicated by ID is deleted.
+ * 
+ *  @param[in] id is the semaphore id
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
  */
 rtems_status_code rtems_semaphore_delete(
   rtems_id   id
diff --git a/cpukit/rtems/include/rtems/rtems/signalmp.h b/cpukit/rtems/include/rtems/rtems/signalmp.h
index d05daa8dd2..2b373a92ed 100644
--- a/cpukit/rtems/include/rtems/rtems/signalmp.h
+++ b/cpukit/rtems/include/rtems/rtems/signalmp.h
@@ -65,7 +65,7 @@ typedef struct {
  */
 
 /**
- *  @brief Signal_MP_Send_request_packet
+ *  @brief Signal MP Send Request Packet
  *
  *  This routine performs a remote procedure call so that a
  *  directive operation can be initiated on another node.
@@ -77,7 +77,7 @@ rtems_status_code _Signal_MP_Send_request_packet (
 );
 
 /**
- *  @brief Signal_MP_Send_response_packet
+ *  @brief Signal MP Send Response Packet
  *
  *  This routine performs a remote procedure call so that a
  *  directive can be performed on another node.
@@ -88,7 +88,7 @@ void _Signal_MP_Send_response_packet (
 );
 
 /**
- *  @brief Signal_MP_Process_packet
+ *  @brief Signal MP Process Packet
  *
  *  This routine performs the actions specific to this package for
  *  the request from another node.
@@ -120,7 +120,7 @@ void _Signal_MP_Process_packet (
  */
 
 /**
- *  @brief Signal_MP_Get_packet
+ *  @brief Signal MP Get Packet
  *
  *  This function is used to obtain a signal mp packet.
  */
diff --git a/cpukit/rtems/include/rtems/rtems/status.h b/cpukit/rtems/include/rtems/rtems/status.h
index 2718d4f063..bb2646e24e 100644
--- a/cpukit/rtems/include/rtems/rtems/status.h
+++ b/cpukit/rtems/include/rtems/rtems/status.h
@@ -183,6 +183,8 @@ typedef enum {
 #define RTEMS_STATUS_CODES_LAST  RTEMS_PROXY_BLOCKING
 
 /**
+ *  @brief Status Object Name Errors to Status Array
+ * 
  *  This array is used to map SuperCore Object Handler return
  *  codes to Classic API status codes.
  */
diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h
index 03795d5e37..90379c17d2 100644
--- a/cpukit/rtems/include/rtems/rtems/tasks.h
+++ b/cpukit/rtems/include/rtems/rtems/tasks.h
@@ -324,11 +324,19 @@ rtems_status_code rtems_task_get_note(
 );
 
 /**
- *  @brief rtems_task_set_note
+ *  @brief RTEMS Set Task Note
  *
  *  This routine implements the rtems_task_set_note directive.  The
  *  value of the indicated notepad for the task associated with ID
  *  is returned in note.
+ * 
+ *  @param[in] id is the thread id
+ *  @param[in] notepad is the notepad number
+ *  @param[in] note is the note value
+ *  
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
  */
 rtems_status_code rtems_task_set_note(
   rtems_id   id,
@@ -378,10 +386,16 @@ rtems_status_code rtems_task_suspend(
 );
 
 /**
- *  @brief rtems_task_resume
+ *  @brief RTEMS Resume Task
  *
  *  This routine implements the rtems_task_resume Directive.  The
  *  SUSPENDED state is cleared for task associated with ID.
+ * 
+ *  @param[in] id is the thread id
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
  */
 rtems_status_code rtems_task_resume(
   rtems_id   id
diff --git a/cpukit/rtems/include/rtems/rtems/timer.h b/cpukit/rtems/include/rtems/rtems/timer.h
index b75a474358..ee35fecce8 100644
--- a/cpukit/rtems/include/rtems/rtems/timer.h
+++ b/cpukit/rtems/include/rtems/rtems/timer.h
@@ -37,6 +37,8 @@
 #define _RTEMS_RTEMS_TIMER_H
 
 /**
+ *  @brief Instantiate RTEMS Timer Data
+ *  
  *  This constant is defined to extern most of the time when using
  *  this header file.  However by defining it to nothing, the data
  *  declared in this header file can be instantiated.  This is done