rtems misc: Clean up Doxygen GCI Task #6

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

8 files changed, 123 insertions, 26 deletions

diff --git a/cpukit/rtems/include/rtems/rtems/barrier.h b/cpukit/rtems/include/rtems/rtems/barrier.h
index df0e6f2c1d..4884d2c014 100644
--- a/cpukit/rtems/include/rtems/rtems/barrier.h
+++ b/cpukit/rtems/include/rtems/rtems/barrier.h
@@ -125,10 +125,12 @@ rtems_status_code rtems_barrier_ident(
 );
 
 /**
- *  @brief rtems_barrier_delete
+ *  @brief RTEMS Delete Barrier
  *
  *  This routine implements the rtems_barrier_delete directive.  The
- *  barrier indicated by @a id is deleted.
+ *  barrier indicated by @a id is deleted.  The barrier is freed back to the
+ *  inactive barrier chain.
+ *
  *
  *  @param[in] id indicates the barrier to delete
  *
diff --git a/cpukit/rtems/include/rtems/rtems/dpmem.h b/cpukit/rtems/include/rtems/rtems/dpmem.h
index a4cf2517ce..e305b31823 100644
--- a/cpukit/rtems/include/rtems/rtems/dpmem.h
+++ b/cpukit/rtems/include/rtems/rtems/dpmem.h
@@ -84,13 +84,24 @@ RTEMS_DPMEM_EXTERN Objects_Information  _Dual_ported_memory_Information;
 void _Dual_ported_memory_Manager_initialization(void);
 
 /**
- *  @brief rtems_port_create
+ *  @brief RTEMS Create Port
  *
  *  This routine implements the rtems_port_create directive.  The port
  *  will have the name name.  The port maps onto an area of dual ported
  *  memory of length bytes which has internal_start and external_start
  *  as the internal and external starting addresses, respectively.
  *  It returns the id of the created port in ID.
+ * 
+ *  @param[in] name is the user defined port name
+ *  @param[in] internal_start is the internal start address of port
+ *  @param[in] external_start is the external start address of port
+ *  @param[in] length is the physical length in bytes
+ *  @param[in] id is the address of port id to set
+ * 
+ *  @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 id will
+ *          be filled in with the port id.
  */
 rtems_status_code rtems_port_create(
   rtems_name    name,
@@ -118,10 +129,16 @@ rtems_status_code rtems_port_ident(
 );
 
 /**
- *  @brief rtems_port_delete
+ *  @brief RTEMS Delete Port
  *
  *  This routine implements the rtems_port_delete directive.  It deletes
  *  the port associated with ID.
+ * 
+ *  @param[in] id is the dual-ported memory area 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_port_delete(
   rtems_id   id
diff --git a/cpukit/rtems/include/rtems/rtems/modes.h b/cpukit/rtems/include/rtems/rtems/modes.h
index 0dbf91bf27..f80cb449cc 100644
--- a/cpukit/rtems/include/rtems/rtems/modes.h
+++ b/cpukit/rtems/include/rtems/rtems/modes.h
@@ -102,7 +102,7 @@ typedef uint32_t   Modes_Control;
 extern const uint32_t rtems_interrupt_mask;
 
 /**
- *  @brief Body for RTEMS_INTERRUPT_LEVEL macro.
+ *  @brief Body for RTEMS_INTERRUPT_LEVEL Macro
  *
  *  @param[in] level is the desired interrupt level
  *
diff --git a/cpukit/rtems/include/rtems/rtems/part.h b/cpukit/rtems/include/rtems/rtems/part.h
index b6b5b3a3dc..d46be0a6c4 100644
--- a/cpukit/rtems/include/rtems/rtems/part.h
+++ b/cpukit/rtems/include/rtems/rtems/part.h
@@ -84,7 +84,7 @@ typedef struct {
 RTEMS_PART_EXTERN Objects_Information _Partition_Information;
 
 /**
- *  @brief Partition_Manager_initialization
+ *  @brief Partition 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 055e25d570..f58bdff53d 100644
--- a/cpukit/rtems/include/rtems/rtems/region.h
+++ b/cpukit/rtems/include/rtems/rtems/region.h
@@ -109,12 +109,20 @@ rtems_status_code rtems_region_create(
 );
 
 /**
- *  @brief rtems_region_extend
+ *  @brief RTEMS Extend Region
  *
  *  This routine implements the rtems_region_extend directive.  The
  *  region will have the name name.  The memory area managed by
  *  the region will be attempted to be grown by length bytes using
  *  the memory starting at starting_address.
+ * 
+ *  @param[in] id is the id of region to grow
+ *  @param[in] starting_address starting address of memory area for extension
+ *  @param[in] length is the physical length in bytes to grow the region
+ * 
+ *  @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_region_extend(
   rtems_id            id,
@@ -123,12 +131,20 @@ rtems_status_code rtems_region_extend(
 );
 
 /**
- *  @brief rtems_region_ident
+ *  @brief RTEMS Region Name to Id
  *
  *  This routine implements the rtems_region_ident directive.
  *  This directive returns the region ID associated with name.
  *  If more than one region is named name, then the region
  *  to which the ID belongs is arbitrary.
+ * 
+ *  @param[in] name is the user defined region name
+ *  @param[in] id is the pointer to region 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.  If successful, the id will
+ *          be filled in with the region id.
  */
 rtems_status_code rtems_region_ident(
   rtems_name    name,
@@ -166,10 +182,17 @@ rtems_status_code rtems_region_get_free_information(
 );
 
 /**
- *  @brief rtems_region_delete
+ *  @brief RTEMS Delete Region
  *
  *  This routine implements the rtems_region_delete directive.  The
- *  region indicated by ID is deleted.
+ *  region indicated by ID is deleted, provided that none of its segments are
+ *  still allocated.
+ * 
+ *  @param[in] id is the region 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_region_delete(
   rtems_id   id
@@ -206,10 +229,19 @@ rtems_status_code rtems_region_get_segment(
 );
 
 /**
- *  @brief rtems_region_get_segment_size
+ *  @brief RTEMS Get Region Segment Size
  *
  *  This routine implements the rtems_region_get_segment_size directive.  It
  *  returns the size in bytes of the specified user memory area.
+ *  
+ *  @param[in] id is the region id
+ *  @param[in] segment is the segment address
+ *  @param[in] size is the pointer to segment size in bytes
+ * 
+ *  @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 size will
+ *          be filled in with the segment size in bytes.
  */
 rtems_status_code rtems_region_get_segment_size(
   rtems_id           id,
diff --git a/cpukit/rtems/include/rtems/rtems/sem.h b/cpukit/rtems/include/rtems/rtems/sem.h
index 23220887d0..aedc5ea961 100644
--- a/cpukit/rtems/include/rtems/rtems/sem.h
+++ b/cpukit/rtems/include/rtems/rtems/sem.h
@@ -229,20 +229,28 @@ bool _Semaphore_Seize(
 );
 
 /**
- *  @brief _Semaphore_Translate_core_mutex_return_code
+ *  @brief Semaphore Translate Core Mutex Return Code
  *
  *  This function returns a RTEMS status code based on the mutex
  *  status code specified.
+ *  
+ *  @param[in] the_mutex_status is the mutex status code to translate
+ * 
+ *  @return translated RTEMS status code
  */
 rtems_status_code _Semaphore_Translate_core_mutex_return_code (
   uint32_t   the_mutex_status
 );
 
 /**
- *  @brief _Semaphore_Translate_core_semaphore_return_code
+ *  @brief Semaphore Translate Core Semaphore Return Code
  *
  *  This function returns a RTEMS status code based on the semaphore
  *  status code specified.
+ * 
+ *  @param[in] status is the semaphore status code to translate
+ * 
+ *  @return translated RTEMS status code
  */
 rtems_status_code _Semaphore_Translate_core_semaphore_return_code (
   uint32_t   the_mutex_status
diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h
index 90379c17d2..abd7d1f946 100644
--- a/cpukit/rtems/include/rtems/rtems/tasks.h
+++ b/cpukit/rtems/include/rtems/rtems/tasks.h
@@ -278,7 +278,7 @@ rtems_status_code rtems_task_create(
 );
 
 /**
- *  @brief rtems_task_ident
+ *  @brief RTEMS Task Name to Id
  *
  *  This routine implements the rtems_task_ident directive.
  *  This directive returns the task ID associated with name.
@@ -287,6 +287,15 @@ rtems_status_code rtems_task_create(
  *  extent of the search for the ID of the task named name.
  *  The search can be limited to a particular node or allowed to
  *  encompass all nodes.
+ * 
+ *  @param[in] name is the user defined thread name
+ *  @param[in] node is(are) the node(s) to be searched
+ *  @param[in] id is the pointer to 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.  If successful, the id will
+ *          be filled in with the thread id.
  */
 rtems_status_code rtems_task_ident(
   rtems_name    name,
@@ -295,10 +304,18 @@ rtems_status_code rtems_task_ident(
 );
 
 /**
- *  @brief rtems_task_delete
+ *  @brief RTEMS Delete Task
  *
  *  This routine implements the rtems_task_delete directive.  The
- *  task indicated by ID is deleted.
+ *  task indicated by ID is deleted. The executive halts execution
+ *  of the thread and frees the thread control block.
+ *  
+ *  @param[in] id is the thread id
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error and id is not the requesting thread.  Status code is
+ *          returned indicating the source of the error.  Nothing
+ *          is returned if id is the requesting thread (always succeeds).
  */
 rtems_status_code rtems_task_delete(
   rtems_id   id
@@ -376,10 +393,17 @@ rtems_status_code rtems_task_restart(
 );
 
 /**
- *  @brief rtems_task_suspend
+ *  @brief RTEMS Suspend Task
  *
  *  This routine implements the rtems_task_suspend directive.  The
- *  SUSPENDED state is set for task associated with ID.
+ *  SUSPENDED state is set for task associated with ID. Note that the
+ *  suspended state can be in addition to other waiting states.
+ * 
+ *  @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_suspend(
   rtems_id   id
@@ -522,14 +546,10 @@ rtems_id rtems_task_self(void);
 void _RTEMS_tasks_Initialize_user_tasks( void );
 
 /**
- *  @brief _RTEMS_Tasks_Invoke_task_variable_dtor
+ *  @brief RTEMS Tasks Invoke Task Variable Destructor
  *
  *  This routine invokes the optional user provided destructor on the
  *  task variable and frees the memory for the task variable.
- *
- *  Input parameters: NONE
- *
- *  Output parameters:  NONE
  */
 void _RTEMS_Tasks_Invoke_task_variable_dtor(
   Thread_Control        *the_thread,
diff --git a/cpukit/rtems/include/rtems/rtems/timer.h b/cpukit/rtems/include/rtems/rtems/timer.h
index ee35fecce8..b7ab2e2743 100644
--- a/cpukit/rtems/include/rtems/rtems/timer.h
+++ b/cpukit/rtems/include/rtems/rtems/timer.h
@@ -222,7 +222,7 @@ RTEMS_TIMER_EXTERN Timer_server_Control *volatile _Timer_server;
 RTEMS_TIMER_EXTERN Objects_Information  _Timer_Information;
 
 /**
- *  @brief _Timer_Manager_initialization
+ *  @brief Timer Manager Initialization
  *
  *  This routine performs the initialization necessary for this manager.
  */
@@ -301,13 +301,22 @@ rtems_status_code rtems_timer_fire_after(
 );
 
 /**
- *  @brief rtems_timer_server_fire_after
+ *  @brief RTEMS Timer Server Fire After
  *
  *  This routine implements the rtems_timer_server_fire_after directive.  It
  *  initiates the timer associated with ID to fire in ticks clock
  *  ticks.  When the timer fires, the routine will be invoked by the
  *  Timer Server in the context of a task NOT IN THE CONTEXT of the
  *  clock tick interrupt.
+ * 
+ *  @param[in] id is the timer id
+ *  @param[in] ticks is the interval until routine is fired
+ *  @param[in] routine is the routine to schedule
+ *  @param[in] user_data is the passed as argument to routine when it is fired
+ * 
+ *  @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_timer_server_fire_after(
   rtems_id                           id,
@@ -317,13 +326,22 @@ rtems_status_code rtems_timer_server_fire_after(
 );
 
 /**
- *  @brief rtems_timer_fire_when
+ *  @brief RTEMS Timer Fire When
  *
  *  This routine implements the rtems_timer_fire_when directive.  It
  *  initiates the timer associated with ID to fire at wall_time
  *  When the timer fires, the routine will be invoked in the context
  *  of the rtems_clock_tick directive which is normally invoked as
  *  part of servicing a periodic interupt.
+ * 
+ *  @param[in] id is the timer id
+ *  @param[in] wall_time is the time of day to fire timer
+ *  @param[in] routine is the routine to schedule
+ *  @param[in] user_data is the passed as argument to routine when it is fired
+ * 
+ *  @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_timer_fire_when(
   rtems_id                            id,