score misc: Clean up Doxygen #14 (GCI 2012)

This patch is a task from GCI 2012 which improves the Doxygen
comments in the RTEMS source.

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

11 files changed, 90 insertions, 22 deletions

diff --git a/cpukit/rtems/include/rtems/rtems/barrier.h b/cpukit/rtems/include/rtems/rtems/barrier.h
index 3e3aa003aa..df0e6f2c1d 100644
--- a/cpukit/rtems/include/rtems/rtems/barrier.h
+++ b/cpukit/rtems/include/rtems/rtems/barrier.h
@@ -104,7 +104,7 @@ rtems_status_code rtems_barrier_create(
 );
 
 /**
- *  @brief rtems_barrier_ident
+ *  @brief RTEMS Barrier name to Id
  *
  *  This routine implements the rtems_barrier_ident directive.
  *  This directive returns the barrier ID associated with name.
@@ -139,7 +139,7 @@ rtems_status_code rtems_barrier_delete(
 );
 
 /**
- *  @brief rtems_barrier_wait
+ *  @brief RTEMS Barrier Wait
  *
  *  This routine implements the rtems_barrier_wait directive.  It
  *  attempts to wait at the barrier associated with @a id.  The calling task
diff --git a/cpukit/rtems/include/rtems/rtems/clock.h b/cpukit/rtems/include/rtems/rtems/clock.h
index c7b9a4ab93..7c12cce708 100644
--- a/cpukit/rtems/include/rtems/rtems/clock.h
+++ b/cpukit/rtems/include/rtems/rtems/clock.h
@@ -228,7 +228,7 @@ rtems_status_code rtems_clock_get_uptime(
 );
 
 /**
- *  @brief Gets the system uptime in the struct timeval format.
+ *  @brief Gets the System Uptime in the Struct Timeval Format
  *
  *  @param[out] Returns the system uptime.  Pointer must not be NULL.
  */
diff --git a/cpukit/rtems/include/rtems/rtems/event.h b/cpukit/rtems/include/rtems/rtems/event.h
index 4dab0ec16c..8386c43e15 100644
--- a/cpukit/rtems/include/rtems/rtems/event.h
+++ b/cpukit/rtems/include/rtems/rtems/event.h
@@ -98,7 +98,7 @@ extern "C" {
  */
 
 /**
- *  @brief Sends an event set to the target task.
+ *  @brief Sends an Event Set to the Target Task
  *
  *  This directive sends an event set @a event_in to the task specified by
  *  @a id.
@@ -453,6 +453,14 @@ void _Event_Seize(
   States_Control                    wait_state
 );
 
+/**
+ *  @brief Surrender Event
+ * 
+ *  - INTERRUPT LATENCY:
+ *    + before flash
+ *    + after flash
+ *    + check sync
+ */
 void _Event_Surrender(
   Thread_Control                   *the_thread,
   rtems_event_set                   event_in,
diff --git a/cpukit/rtems/include/rtems/rtems/message.h b/cpukit/rtems/include/rtems/rtems/message.h
index 31844d6afa..69eab62d7c 100644
--- a/cpukit/rtems/include/rtems/rtems/message.h
+++ b/cpukit/rtems/include/rtems/rtems/message.h
@@ -122,7 +122,7 @@ rtems_status_code rtems_message_queue_create(
 );
 
 /**
- *  @brief rtems_message_queue_ident
+ *  @brief RTEMS Message Queue Name to Id
  *
  *  This routine implements the rtems_message_queue_ident directive.
  *  This directive returns the message queue ID associated with NAME.
@@ -131,6 +131,13 @@ rtems_status_code rtems_message_queue_create(
  *  extent of the search for the ID of the message queue named name.
  *  The search can be limited to a particular node or allowed to
  *  encompass all nodes.
+ *  
+ *  @param[in] name is the user defined message queue name
+ *  @param[in] node is the node(s) to be searched
+ *  @param[in] id is the pointer to message queue id
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
+ *  *id filled with the message queue id
  */
 rtems_status_code rtems_message_queue_ident(
   rtems_name  name,
@@ -139,10 +146,14 @@ rtems_status_code rtems_message_queue_ident(
 );
 
 /**
- *  @brief rtems_message_queue_delete
+ *  @brief RTEMS Delete Message Queue
  *
  *  This routine implements the rtems_message_queue_delete directive.  The
  *  message queue indicated by ID is deleted.
+ * 
+ *  @param[in] id is the queue id
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_message_queue_delete(
   rtems_id id
diff --git a/cpukit/rtems/include/rtems/rtems/ratemon.h b/cpukit/rtems/include/rtems/rtems/ratemon.h
index c3892092d3..93c8e26ba5 100644
--- a/cpukit/rtems/include/rtems/rtems/ratemon.h
+++ b/cpukit/rtems/include/rtems/rtems/ratemon.h
@@ -297,11 +297,17 @@ rtems_status_code rtems_rate_monotonic_ident(
 );
 
 /**
- *  @brief rtems_rate_monotonic_cancel
+ *  @brief RTEMS Rate Monotonic Cancel
  *
  *  This routine implements the rtems_rate_monotonic_cancel directive.  This
  *  directive stops the period associated with ID from continuing to
  *  run.
+ * 
+ *  @param[in] id is the rate monotonic id
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful and caller is not the owning thread
+ *  or error code if unsuccessful
+ *  
  */
 rtems_status_code rtems_rate_monotonic_cancel(
   rtems_id   id
@@ -318,7 +324,7 @@ rtems_status_code rtems_rate_monotonic_delete(
 );
 
 /**
- *  @brief rtems_rate_monotonic_get_status
+ *  @brief RTEMS Rate Monotonic Get Status
  *
  *  This routine implements the rtems_rate_monotonic_get_status directive.
  *  Information about the period indicated by ID is returned.
@@ -330,10 +336,15 @@ rtems_status_code rtems_rate_monotonic_get_status(
 );
 
 /**
- *  @brief rtems_rate_monotonic_get_statistics
+ *  @brief RTEMS Rate Monotonic Get Statistics
  *
  *  This routine implements the rtems_rate_monotonic_get_statistics directive.
  *  Statistics gathered from the use of this period are returned.
+ * 
+ *  @param[in] id is the rate monotonic id
+ *  @param[in] statistics is the pointer to statistics control block
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_rate_monotonic_get_statistics(
   rtems_id                                id,
@@ -378,12 +389,17 @@ void rtems_rate_monotonic_report_statistics_with_plugin(
 void rtems_rate_monotonic_report_statistics( void );
 
 /**
- *  @brief rtems_rate_monotonic_period
+ *  @brief RTEMS Rate Monotonic Period
  *
  *  This routine implements the rtems_rate_monotonic_period directive.  When
  *  length is non-zero, this directive initiates the period associated with
  *  ID from continuing for a period of length.  If length is zero, then
  *  result is set to indicate the current state of the period.
+ *  
+ *  @param[in] id is the rate monotonic id
+ *  @param[in] lenght is the length of period (in ticks)
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_rate_monotonic_period(
   rtems_id        id,
@@ -429,7 +445,7 @@ bool _Rate_monotonic_Get_status(
 );
 
 /**
- *  @brief _Rate_monotonic_Initiate_statistics(
+ *  @brief Initiate Rate Monotonic Statistics
  *
  *  This routine is invoked when a period is initiated via an explicit
  *  call to rtems_rate_monotonic_period for the period's first iteration
diff --git a/cpukit/rtems/include/rtems/rtems/region.h b/cpukit/rtems/include/rtems/rtems/region.h
index c14c3489b6..a35acf97e2 100644
--- a/cpukit/rtems/include/rtems/rtems/region.h
+++ b/cpukit/rtems/include/rtems/rtems/region.h
@@ -136,11 +136,17 @@ rtems_status_code rtems_region_ident(
 );
 
 /**
- *  @brief rtems_region_get_information
+ *  @brief RTEMS Get Region Information
  *
  *  This routine implements the rtems_region_get_information directive.
  *  This directive returns information about the heap associated with
  *  this region.
+ * 
+ *  @param[in] id is the region id
+ *  @param[in] the_info is the pointer to region information block
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
+ *  *id filled with the region information block
  */
 rtems_status_code rtems_region_get_information(
   rtems_id                id,
@@ -249,11 +255,13 @@ rtems_status_code rtems_region_resize_segment(
 #ifndef __RTEMS_APPLICATION__
 #include <rtems/rtems/region.inl>
 /**
- *  @brief Region_Process_queue
+ *  @brief Process Region Queue
  *
  *  This is a helper routine which is invoked any time memory is
  *  freed.  It looks at the set of waiting tasks and attempts to
  *  satisfy all outstanding requests.
+ * 
+ *  @param[in] the_region is the the region
  */
 extern void _Region_Process_queue(Region_Control *the_region);
 
diff --git a/cpukit/rtems/include/rtems/rtems/sem.h b/cpukit/rtems/include/rtems/rtems/sem.h
index 4475d030c2..a75ef4130a 100644
--- a/cpukit/rtems/include/rtems/rtems/sem.h
+++ b/cpukit/rtems/include/rtems/rtems/sem.h
@@ -128,7 +128,7 @@ rtems_status_code rtems_semaphore_create(
 );
 
 /**
- *  @brief rtems_semaphore_ident
+ *  @brief RTEMS Semaphore Name to Id
  *
  *  This routine implements the rtems_semaphore_ident directive.
  *  This directive returns the semaphore ID associated with name.
@@ -137,6 +137,13 @@ rtems_status_code rtems_semaphore_create(
  *  extent of the search for the ID of the semaphore named name.
  *  The search can be limited to a particular node or allowed to
  *  encompass all nodes.
+ * 
+ *  @param[in] name is the user defined semaphore name
+ *  @param[in] node is(are) the node(s) to be searched
+ *  @param[in] id is the pointer to semaphore id
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
+ *  *id filled in with the semaphore id
  */
 rtems_status_code rtems_semaphore_ident(
   rtems_name    name,
diff --git a/cpukit/rtems/include/rtems/rtems/signal.h b/cpukit/rtems/include/rtems/rtems/signal.h
index f804e5ef70..046842f97f 100644
--- a/cpukit/rtems/include/rtems/rtems/signal.h
+++ b/cpukit/rtems/include/rtems/rtems/signal.h
@@ -61,10 +61,15 @@ rtems_status_code rtems_signal_catch(
 );
 
 /**
- *  @brief rtems_signal_send
+ *  @brief RTEMS Send Signal
  *
  *  This routine implements the rtems_signal_send directive.  This directive
  *  sends the signal_set to the task specified by ID.
+ * 
+ *  @param[in] id is the thread thread id
+ *  @param[in] signal_set is the signal set
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_signal_send(
   rtems_id         id,
diff --git a/cpukit/rtems/include/rtems/rtems/support.h b/cpukit/rtems/include/rtems/rtems/support.h
index b2c6471c31..99bf405a21 100644
--- a/cpukit/rtems/include/rtems/rtems/support.h
+++ b/cpukit/rtems/include/rtems/rtems/support.h
@@ -100,13 +100,13 @@ bool rtems_workspace_free(
 );
 
 /**
- * @brief Greedy allocate that empties the workspace.
+ *  @brief Greedy Allocate that Empties the Workspace
  *
- * Afterward the heap has at most @a block_count allocateable blocks of sizes
- * specified by @a block_sizes.  The @a block_sizes must point to an array with
- * @a block_count members.  All other blocks are used.
+ *  Afterward the heap has at most @a block_count allocateable blocks of sizes
+ *  specified by @a block_sizes.  The @a block_sizes must point to an array with
+ *  @a block_count members.  All other blocks are used.
  *
- * @see rtems_workspace_greedy_free().
+ *  @see rtems_workspace_greedy_free().
  */
 void *rtems_workspace_greedy_allocate(
   const uintptr_t *block_sizes,
diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h
index e80df03103..b6b1c1c5b2 100644
--- a/cpukit/rtems/include/rtems/rtems/tasks.h
+++ b/cpukit/rtems/include/rtems/rtems/tasks.h
@@ -375,12 +375,19 @@ rtems_status_code rtems_task_resume(
 );
 
 /**
- *  @brief rtems_task_set_priority
+ *  @brief RTEMS Set Task Priority
  *
  *  This routine implements the rtems_task_set_priority directive.  The
  *  current priority of the task associated with ID is set to
  *  new_priority.  The former priority of that task is returned
  *  in old_priority.
+ * 
+ *  @param[in] id is the thread to extract
+ *  @param[in] new_priority is the thread to extract
+ *  @param[in] old_priority is the thread to extract
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
+ *  and *old_priority filled in with the previous previous priority
  */
 rtems_status_code rtems_task_set_priority(
   rtems_id             id,
diff --git a/cpukit/rtems/include/rtems/rtems/timer.h b/cpukit/rtems/include/rtems/rtems/timer.h
index ea09bc09d4..982f5dabd0 100644
--- a/cpukit/rtems/include/rtems/rtems/timer.h
+++ b/cpukit/rtems/include/rtems/rtems/timer.h
@@ -239,12 +239,18 @@ rtems_status_code rtems_timer_create(
 );
 
 /**
- *  @brief rtems_timer_ident
+ *  @brief RTEMS Timer Name to Id
  *
  *  This routine implements the rtems_timer_ident directive.
  *  This directive returns the timer ID associated with name.
  *  If more than one timer is named name, then the timer
  *  to which the ID belongs is arbitrary.
+ * 
+ *  @param[in] name is the user defined message queue name
+ *  @param[in] id is the pointer to timer id
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
+ *  id filled with the message queue id
  */
 rtems_status_code rtems_timer_ident(
   rtems_name    name,