capture: Update comment block style in capture engine.

Doxygen added and comment blocks standardized.

2 files changed, 378 insertions, 416 deletions

diff --git a/cpukit/libmisc/capture/capture.c b/cpukit/libmisc/capture/capture.c
index 118e4ff5b3..6f8e0a242d 100644
--- a/cpukit/libmisc/capture/capture.c
+++ b/cpukit/libmisc/capture/capture.c
@@ -109,10 +109,6 @@ static const char* capture_event_text[] =
 };
 
 /*
- * rtems_capture_get_time
- *
- *  DESCRIPTION:
- *
  * This function returns the current time. If a handler is provided
  * by the user get the time from that.
  */
@@ -128,14 +124,9 @@ rtems_capture_get_time (rtems_capture_time_t* time)
 }
 
 /*
- * rtems_capture_match_names
- *
- *  DESCRIPTION:
- *
  * This function compares rtems_names. It protects the
  * capture engine from a change to the way names are supported
  * in RTEMS.
- *
  */
 static inline bool
 rtems_capture_match_names (rtems_name lhs, rtems_name rhs)
@@ -144,14 +135,9 @@ rtems_capture_match_names (rtems_name lhs, rtems_name rhs)
 }
 
 /*
- * rtems_capture_match_id
- *
- *  DESCRIPTION:
- *
  * This function compares rtems_ids. It protects the
  * capture engine from a change to the way id are supported
  * in RTEMS.
- *
  */
 static inline bool
 rtems_capture_match_ids (rtems_id lhs, rtems_id rhs)
@@ -160,10 +146,6 @@ rtems_capture_match_ids (rtems_id lhs, rtems_id rhs)
 }
 
 /*
- * rtems_capture_match_name_id
- *
- *  DESCRIPTION:
- *
  * This function matches a name and/or id.
  */
 static inline bool
@@ -186,14 +168,9 @@ rtems_capture_match_name_id (rtems_name lhs_name,
 }
 
 /*
- * rtems_capture_dup_name
- *
- *  DESCRIPTION:
- *
  * This function duplicates an rtems_names. It protects the
  * capture engine from a change to the way names are supported
  * in RTEMS.
- *
  */
 static inline void
 rtems_capture_dup_name (rtems_name* dst, rtems_name src)
@@ -202,14 +179,9 @@ rtems_capture_dup_name (rtems_name* dst, rtems_name src)
 }
 
 /*
- * rtems_capture_by_in_to
- *
- *  DESCRIPTION:
- *
  * This function sees if a BY control is in the BY names. The use
  * of the valid_mask in this way assumes the number of trigger
  * tasks is the number of bits in uint32_t.
- *
  */
 static inline bool
 rtems_capture_by_in_to (uint32_t                 events,
@@ -253,12 +225,7 @@ rtems_capture_by_in_to (uint32_t                 events,
 }
 
 /*
- * rtems_capture_refcount_up
- *
- *  DESCRIPTION:
- *
  * This function raises the reference count.
- *
  */
 static inline void
 rtems_capture_refcount_up (rtems_capture_task_t* task)
@@ -267,13 +234,8 @@ rtems_capture_refcount_up (rtems_capture_task_t* task)
 }
 
 /*
- * rtems_capture_refcount_down
- *
- *  DESCRIPTION:
- *
  * This function lowers the reference count and if the count
  * reaches 0 the task control block is returned to the heap.
- *
  */
 static inline void
 rtems_capture_refcount_down (rtems_capture_task_t* task)
@@ -283,10 +245,6 @@ rtems_capture_refcount_down (rtems_capture_task_t* task)
 }
 
 /*
- * rtems_capture_init_stack_usage
- *
- *  DESCRIPTION:
- *
  * This function setups a stack so its usage can be monitored.
  */
 static inline void
@@ -308,12 +266,7 @@ rtems_capture_init_stack_usage (rtems_capture_task_t* task)
 }
 
 /*
- * rtems_capture_find_control
- *
- *  DESCRIPTION:
- *
  * This function searches for a trigger given a name.
- *
  */
 static inline rtems_capture_control_t*
 rtems_capture_find_control (rtems_name name, rtems_id id)
@@ -327,12 +280,7 @@ rtems_capture_find_control (rtems_name name, rtems_id id)
 }
 
 /*
- * rtems_capture_create_control
- *
- *  DESCRIPTION:
- *
  * This function creates a capture control for the capture engine.
- *
  */
 static inline rtems_capture_control_t*
 rtems_capture_create_control (rtems_name name, rtems_id id)
@@ -385,12 +333,7 @@ rtems_capture_create_control (rtems_name name, rtems_id id)
 }
 
 /*
- * rtems_capture_create_capture_task
- *
- *  DESCRIPTION:
- *
  * This function create the task control.
- *
  */
 static inline rtems_capture_task_t*
 rtems_capture_create_capture_task (rtems_tcb* new_task)
@@ -466,14 +409,9 @@ rtems_capture_create_capture_task (rtems_tcb* new_task)
 }
 
 /*
- * rtems_capture_destroy_capture_task
- *
- *  DESCRIPTION:
- *
  * This function destroy the task structure if the reference count
  * is 0 and the tcb has been cleared signalling the task has been
  * deleted.
- *
  */
 static inline void
 rtems_capture_destroy_capture_task (rtems_capture_task_t* task)
@@ -504,12 +442,7 @@ rtems_capture_destroy_capture_task (rtems_capture_task_t* task)
 }
 
 /*
- * rtems_capture_record
- *
- *  DESCRIPTION:
- *
  * This function records a capture record into the capture buffer.
- *
  */
 static inline void
 rtems_capture_record (rtems_capture_task_t* task,
@@ -529,11 +462,10 @@ rtems_capture_record (rtems_capture_task_t* task,
     control = task->control;
 
     /*
-     * Capure the record if we have an event that is always
+     * Capture the record if we have an event that is always
      * captured, or the task's real priority is greater than the
      * watch ceiling, and the global watch or task watch is enabled.
      */
-
     if ((events & RTEMS_CAPTURE_RECORD_EVENTS) ||
         ((task->tcb->real_priority >= capture_ceiling) &&
          (task->tcb->real_priority <= capture_floor) &&
@@ -572,10 +504,6 @@ rtems_capture_record (rtems_capture_task_t* task,
 }
 
 /*
- * rtems_capture_trigger
- *
- *  DESCRIPTION:
- *
  * See if we have triggered and if not see if this event is a
  * cause of a trigger.
  */
@@ -645,12 +573,7 @@ rtems_capture_trigger (rtems_capture_task_t* ft,
 }
 
 /*
- * rtems_capture_create_task
- *
- *  DESCRIPTION:
- *
  * This function is called when a task is created.
- *
  */
 static bool
 rtems_capture_create_task (rtems_tcb* current_task,
@@ -684,12 +607,7 @@ rtems_capture_create_task (rtems_tcb* current_task,
 }
 
 /*
- * rtems_capture_start_task
- *
- *  DESCRIPTION:
- *
  * This function is called when a task is started.
- *
  */
 static void
 rtems_capture_start_task (rtems_tcb* current_task,
@@ -726,12 +644,7 @@ rtems_capture_start_task (rtems_tcb* current_task,
 }
 
 /*
- * rtems_capture_restart_task
- *
- *  DESCRIPTION:
- *
  * This function is called when a task is restarted.
- *
  */
 static void
 rtems_capture_restart_task (rtems_tcb* current_task,
@@ -769,12 +682,7 @@ rtems_capture_restart_task (rtems_tcb* current_task,
 }
 
 /*
- * rtems_capture_delete_task
- *
- *  DESCRIPTION:
- *
  * This function is called when a task is deleted.
- *
  */
 static void
 rtems_capture_delete_task (rtems_tcb* current_task,
@@ -819,12 +727,7 @@ rtems_capture_delete_task (rtems_tcb* current_task,
 }
 
 /*
- * rtems_capture_begin_task
- *
- *  DESCRIPTION:
- *
  * This function is called when a task is begun.
- *
  */
 static void
 rtems_capture_begin_task (rtems_tcb* begin_task)
@@ -850,13 +753,8 @@ rtems_capture_begin_task (rtems_tcb* begin_task)
 }
 
 /*
- * rtems_capture_exitted_task
- *
- *  DESCRIPTION:
- *
  * This function is called when a task is exitted. That is
  * returned rather than was deleted.
- *
  */
 static void
 rtems_capture_exitted_task (rtems_tcb* exitted_task)
@@ -884,12 +782,28 @@ rtems_capture_exitted_task (rtems_tcb* exitted_task)
 }
 
 /*
- * rtems_capture_switch_task
- *
- *  DESCRIPTION:
- *
+ * This function is called when a termination request is identified.
+ */
+static void
+rtems_capture_terminated_task (rtems_tcb* terminated_task)
+{
+  rtems_capture_delete_task (terminated_task, terminated_task);
+}
+
+/*
+ * This function is called when a fatal error occurs.
+ */
+static void
+rtems_capture_fatal(
+  Internal_errors_Source source,
+  bool                   is_internal,
+  Internal_errors_t      code
+)
+{
+}
+  
+/*
  * This function is called when a context is switched.
- *
  */
 static void
 rtems_capture_switch_task (rtems_tcb* current_task,
@@ -967,13 +881,8 @@ rtems_capture_switch_task (rtems_tcb* current_task,
 }
 
 /*
- * rtems_capture_open
- *
- *  DESCRIPTION:
- *
  * This function initialises the realtime capture engine allocating the trace
  * buffer. It is assumed we have a working heap at stage of initialisation.
- *
  */
 rtems_status_code
 rtems_capture_open (uint32_t   size, rtems_capture_timestamp timestamp __attribute__((unused)))
@@ -1041,10 +950,6 @@ rtems_capture_open (uint32_t   size, rtems_capture_timestamp timestamp __attribu
 }
 
 /*
- * rtems_capture_close
- *
- *  DESCRIPTION:
- *
  * This function shutdowns the capture engine and release any claimed
  * resources.
  */
@@ -1112,10 +1017,6 @@ rtems_capture_close (void)
 }
 
 /*
- * rtems_capture_control
- *
- *  DESCRIPTION:
- *
  * This function allows control of tracing at a global level.
  */
 static void
@@ -1150,10 +1051,6 @@ rtems_capture_control (bool enable)
 }
 
 /*
- * rtems_capture_monitor
- *
- *  DESCRIPTION:
- *
  * This function enable the monitor mode. When in the monitor mode
  * the tasks are monitored but no data is saved. This can be used
  * to profile the load on a system.
@@ -1182,10 +1079,6 @@ rtems_capture_monitor (bool enable)
 }
 
 /*
- * rtems_capture_flush
- *
- *  DESCRIPTION:
- *
  * This function flushes the capture buffer. The prime parameter allows the
  * capture engine to also be primed again.
  */
@@ -1227,10 +1120,6 @@ rtems_capture_flush (bool prime)
 }
 
 /*
- * rtems_capture_watch_add
- *
- *  DESCRIPTION:
- *
  * This function defines a watch for a specific task given a name. A watch
  * causes it to be traced either in or out of context. The watch can be
  * optionally enabled or disabled with the set routine. It is disabled by
@@ -1259,10 +1148,6 @@ rtems_capture_watch_add (rtems_name name, rtems_id id)
 }
 
 /*
- * rtems_capture_watch_del
- *
- *  DESCRIPTION:
- *
  * This function removes a watch for a specific task given a name. The task
  * description will still exist if referenced by a trace record in the trace
  * buffer or a global watch is defined.
@@ -1315,10 +1200,6 @@ rtems_capture_watch_del (rtems_name name, rtems_id id)
 }
 
 /*
- * rtems_capture_watch_set
- *
- *  DESCRIPTION:
- *
  * This function allows control of a watch. The watch can be enabled or
  * disabled.
  */
@@ -1357,10 +1238,6 @@ rtems_capture_watch_ctrl (rtems_name name, rtems_id id, bool enable)
 }
 
 /*
- * rtems_capture_watch_global
- *
- *  DESCRIPTION:
- *
  * This function allows control of a global watch. The watch can be enabled or
  * disabled. A global watch configures all tasks below the ceiling and above
  * the floor to be traced.
@@ -1387,10 +1264,6 @@ rtems_capture_watch_global (bool enable)
 }
 
 /*
- * rtems_capture_watch_global_on
- *
- *  DESCRIPTION:
- *
  * This function returns the global watch state.
  */
 bool
@@ -1400,10 +1273,6 @@ rtems_capture_watch_global_on (void)
 }
 
 /*
- * rtems_capture_watch_ceiling
- *
- *  DESCRIPTION:
- *
  * This function sets a watch ceiling. Tasks at or greating that the
  * ceiling priority are not watched. This is a simple way to monitor
  * an application and exclude system tasks running at a higher
@@ -1417,10 +1286,6 @@ rtems_capture_watch_ceiling (rtems_task_priority ceiling)
 }
 
 /*
- * rtems_capture_watch_get_ceiling
- *
- *  DESCRIPTION:
- *
  * This function gets the watch ceiling.
  */
 rtems_task_priority
@@ -1430,10 +1295,6 @@ rtems_capture_watch_get_ceiling (void)
 }
 
 /*
- * rtems_capture_watch_floor
- *
- *  DESCRIPTION:
- *
  * This function sets a watch floor. Tasks at or less that the
  * floor priority are not watched. This is a simple way to monitor
  * an application and exclude system tasks running at a lower
@@ -1447,10 +1308,6 @@ rtems_capture_watch_floor (rtems_task_priority floor)
 }
 
 /*
- * rtems_capture_watch_get_floor
- *
- *  DESCRIPTION:
- *
  * This function gets the watch floor.
  */
 rtems_task_priority
@@ -1460,12 +1317,7 @@ rtems_capture_watch_get_floor (void)
 }
 
 /*
- * rtems_capture_map_trigger
- *
- *  DESCRIPTION:
- *
  * Map the trigger to a bit mask.
- *
  */
 static uint32_t
 rtems_capture_map_trigger (rtems_capture_trigger_t trigger)
@@ -1496,10 +1348,6 @@ rtems_capture_map_trigger (rtems_capture_trigger_t trigger)
 }
 
 /*
- * rtems_capture_set_trigger
- *
- *  DESCRIPTION:
- *
  * This function sets a trigger.
  *
  * This set trigger routine will create a capture control for the
@@ -1586,10 +1434,6 @@ rtems_capture_set_trigger (rtems_name                   from_name,
 }
 
 /*
- * rtems_capture_clear_trigger
- *
- *  DESCRIPTION:
- *
  * This function clear a trigger.
  */
 rtems_status_code
@@ -1660,10 +1504,6 @@ rtems_capture_clear_trigger (rtems_name                   from_name,
 }
 
 /*
- * rtems_capture_read
- *
- *  DESCRIPTION:
- *
  * This function reads a number of records from the capture buffer.
  * The user can optionally block and wait until the buffer as a
  * specific number of records available or a specific time has
@@ -1688,7 +1528,6 @@ rtems_capture_clear_trigger (rtems_name                   from_name,
  *
  * The 'timeout' parameter is in micro-seconds. A value of 0 will disable
  * the timeout.
- *
  */
 rtems_status_code
 rtems_capture_read (uint32_t                 threshold,
@@ -1784,10 +1623,6 @@ rtems_capture_read (uint32_t                 threshold,
 }
 
 /*
- * rtems_capture_release
- *
- *  DESCRIPTION:
- *
  * This function releases the requested number of record slots back
  * to the capture engine. The count must match the number read.
  */
@@ -1830,10 +1665,6 @@ rtems_capture_release (uint32_t count)
 }
 
 /*
- * rtems_capture_time
- *
- *  DESCRIPTION:
- *
  * This function returns the current time. If a handler is provided
  * by the user get the time from that.
  */
@@ -1844,10 +1675,6 @@ rtems_capture_time (rtems_capture_time_t* uptime)
 }
 
 /*
- * rtems_capture_event_text
- *
- *  DESCRIPTION:
- *
  * This function returns a string for an event based on the bit in the
  * event. The functions takes the bit offset as a number not the bit
  * set in a bit map.
@@ -1861,10 +1688,6 @@ rtems_capture_event_text (int event)
 }
 
 /*
- * rtems_capture_get_task_list
- *
- *  DESCRIPTION:
- *
  * This function returns the head of the list of tasks that the
  * capture engine has detected.
  */
@@ -1875,10 +1698,6 @@ rtems_capture_get_task_list (void)
 }
 
 /*
- * rtems_capture_task_stack_usage
- *
- *  DESCRIPTION:
- *
  * This function updates the stack usage. The task control block
  * is updated.
  */
@@ -1911,10 +1730,6 @@ rtems_capture_task_stack_usage (rtems_capture_task_t* task)
 }
 
 /*
- * rtems_capture_get_control_list
- *
- *  DESCRIPTION:
- *
  * This function returns the head of the list of control in the
  * capture engine.
  */
diff --git a/cpukit/libmisc/capture/capture.h b/cpukit/libmisc/capture/capture.h
index c9cebc919e..fa82f6dd19 100644
--- a/cpukit/libmisc/capture/capture.h
+++ b/cpukit/libmisc/capture/capture.h
@@ -33,6 +33,14 @@
 #ifndef __CAPTURE_H_
 #define __CAPTURE_H_
 
+/**
+ *  @defgroup libmisc_capture RTEMS Capture Engine
+ *
+ *  @ingroup libmisc
+ *
+ *  Capture Engine Component of the RTEMS Measurement and Monitoring System
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -45,18 +53,14 @@ extern "C" {
 #define RTEMS_CAPTURE_TRIGGER_TASKS (32)
 
 /**
- * rtems_capture_time_t
- *
- * DESCRIPTION:
+ * @brief A capture timestamp.
  *
- * A capture timestamp.
+ * This is a nanosecond capture timestamp
  */
 typedef uint64_t rtems_capture_time_t;
 
 /**
- * rtems_capture_from_t
- *
- *  DESCRIPTION:
+ * @brief Task id and mask for the from trigger.
  *
  * A from capture is a task id and a mask for the type of
  * from trigger we are interested in. The mask uses the same
@@ -72,9 +76,7 @@ typedef struct rtems_capture_from_s
 } rtems_capture_from_t;
 
 /**
- * rtems_capture_control_t
- *
- *  DESCRIPTION:
+ * @brief Capture control structure for a group of tasks.
  *
  * RTEMS control holds the trigger and watch configuration for a group of
  * tasks with the same name. The flags hold global control flags.
@@ -134,9 +136,7 @@ typedef struct rtems_capture_control_s
                                      RTEMS_CAPTURE_EXITTED)
 
 /**
- * rtems_capture_task_t
- *
- *  DESCRIPTION:
+ * @brief Catpure task control
  *
  * RTEMS capture control provdes the information about a task, along
  * with its trigger state. The control is referenced by each
@@ -179,11 +179,9 @@ typedef struct rtems_capture_task_s
 #define RTEMS_CAPTURE_TRACED  (1U << 0)
 
 /*
- * rtems_capture_record_t
+ * @brief Capture record.
  *
- *  DESCRIPTION:
- *
- * RTEMS capture record. This is a record that is written into
+ * This is a record that is written into
  * the buffer. The events includes the priority of the task
  * at the time of the context switch.
  */
@@ -218,9 +216,7 @@ typedef struct rtems_capture_record_s
 #define RTEMS_CAPTURE_EVENT_END           (28)
 
 /**
- * rtems_capture_trigger_mode_t
- *
- *  DESCRIPTION:
+ * @brief Capture trigger modes
  *
  * The types of trigger modes that exist.
  */
@@ -232,9 +228,7 @@ typedef enum rtems_capture_trigger_mode_e
 } rtems_capture_trigger_mode_t;
 
 /**
- * rtems_capture_trigger_t
- *
- *  DESCRIPTION:
+ * @brief Capture trigger.
  *
  * The types of triggers that exist.
  */
@@ -250,9 +244,7 @@ typedef enum rtems_capture_trigger_e
 } rtems_capture_trigger_t;
 
 /**
- * rtems_capture_timestamp
- *
- *  DESCRIPTION:
+ * @brief Capture timestamp callout handler.
  *
  * This defines the callout handler to obtain a time stamp. The
  * value returned is time count since the last read.
@@ -262,95 +254,131 @@ typedef enum rtems_capture_trigger_e
 typedef void (*rtems_capture_timestamp)(rtems_capture_time_t* time);
 
 /**
- * rtems_capture_open
- *
- *  DESCRIPTION:
+ * @brief Capture open
  *
  * This function initialises the realtime trace manager allocating the
  * capture buffer. It is assumed we have a working heap at stage of
  * initialisation.
  *
+ * @param[in] size The number of capture records to define.
+ * @param[in] timestamp The timestamp callout handler to use. If the 
+ *            the handler is NULL a default  nano-second timestamp 
+ *            will be used.
+ *
+ * @retval 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_capture_open (uint32_t                size,
                     rtems_capture_timestamp timestamp);
 
 /**
- * rtems_capture_close
- *
- *  DESCRIPTION:
+ * @brief Capture close
  *
  * This function shutdowns the tracer and release any claimed
  * resources.
+ *
+ * @retval 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_capture_close (void);
 
 /**
- * rtems_capture_control
- *
- *  DESCRIPTION:
+ * @brief Capture control trace enable/disable.
  *
  * This function allows control of tracing at a global level.
+ *
+ * @param[in]  enable The trace enable/disable flag.
+ *
+ * @retval 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_capture_control (bool enable);
 
 /**
- * rtems_capture_monitor
- *
- *  DESCRIPTION:
+ * @brief Capture monitor enable/disable.
  *
  * This function enable the monitor mode. When in the monitor mode
  * the tasks are monitored but no data is saved. This can be used
  * to profile the load on a system.
+ *
+ * @param[in]  enable The monitor enable/disable flag.
+ *
+ * @retval 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_capture_monitor (bool enable);
 
 /*
- * rtems_capture_flush
- *
- *  DESCRIPTION:
+ * @brief Capture flush trace buffer.
  *
  * This function flushes the trace buffer. The prime parameter allows the
  * capture engine to also be primed again.
+ *
+ * @param[in]  prime The prime after flush flag.
+ *
+ * @retval 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_capture_flush (bool prime);
 
 /**
- * rtems_capture_watch_add
- *
- *  DESCRIPTION:
+ * @brief Capture add watch
  *
  * This function defines a watch for a specific task given a name. A watch
  * causes it to be traced either in or out of context. The watch can be
  * optionally enabled or disabled with the set routine. It is disabled by
  * default.
+ *
+ * @param[in]  name The name of the @a capture_controls entry
+ * @param[in]  id The id of the @a capture_controls entry.
+ *
+ * @retval 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_capture_watch_add (rtems_name name, rtems_id id);
 
 /**
- * rtems_capture_watch_del
- *
- *  DESCRIPTION:
+ * @brief Capture delete watch.
  *
  * This function removes a watch for a specific task given a name. The task
  * description will still exist if referenced by a trace record in the trace
  * buffer or a global watch is defined.
+ *
+ * @param[in]  name The name of the @a capture_controls entry
+ * @param[in]  id The id of the @a capture_controls entry.
+ *
+ * @retval 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_capture_watch_del (rtems_name name, rtems_id id);
 
 /**
- * rtems_capture_watch_set
- *
- *  DESCRIPTION:
+ * @brief Capture enable/disable watch.
  *
  * This function allows control of a watch. The watch can be enabled or
  * disabled.
+ *
+ * @param[in]  name The name of the @a capture_controls entry
+ * @param[in]  id The id of the @a capture_controls entry.
+ * @param[in]  enable The enable/disable flag for the watch.
+ *
+ * @retval 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_capture_watch_ctrl (rtems_name    name,
@@ -358,77 +386,92 @@ rtems_capture_watch_ctrl (rtems_name    name,
                           bool enable);
 
 /**
- * rtems_capture_watch_global
- *
- *  DESCRIPTION:
+ * @brief Capture enable/disable global watch.
  *
  * This function allows control of a global watch. The watch can
  * be enabled or disabled. A global watch configures all tasks below
  * the ceiling and above the floor to be traced.
+ *
+ * @param[in]  enable The enable/disable flag for the watch.
+ *
+ * @retval 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_capture_watch_global (bool enable);
 
 /**
- * rtems_capture_watch_global_on
- *
- *  DESCRIPTION:
+ * @brief Get global watch state
  *
  * This function returns the global watch state.
+ *
+ * @retval This method returns true  if the global watch 
+ *         is on.  Otherwise, it returns false.
  */
 bool
 rtems_capture_watch_global_on (void);
 
 /**
- * rtems_capture_watch_ceiling
- *
- *  DESCRIPTION:
+ * @brief Set watch ceiling.
  *
- * This function sets a watch ceiling. Tasks at or greating that the
- * ceiling priority are not watched. This is a simple way to monitor
- * an application and exclude system tasks running at a higher
+ * This function sets a watch ceiling. Events from tasks at or greater
+ * than the ceiling priority are ignored. This is a simple way to
+ * monitor an application and exclude system tasks running at a higher
  * priority level.
+ *
+ * @param[in] ceiling specifies the priority level immediately above
+ *     that at which events from tasks are not captured.
+ *
+ * @retval 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_capture_watch_ceiling (rtems_task_priority ceiling);
 
 /**
- * rtems_capture_watch_get_ceiling
- *
- *  DESCRIPTION:
+ * @brief Get watch ceiling.
  *
  * This function gets the watch ceiling.
+ *
+ * @retval The priority level immediately above that at which events 
+ *         from tasks are not captured.
  */
 rtems_task_priority
 rtems_capture_watch_get_ceiling (void);
 
 /**
- * rtems_capture_watch_floor
- *
- *  DESCRIPTION:
+ * @brief Capture set watch floor.
  *
- * This function sets a watch floor. Tasks at or less that the
+ * This function sets a watch floor. Tasks at or less than the
  * floor priority are not watched. This is a simple way to monitor
  * an application and exclude system tasks running at a lower
  * priority level.
+ *
+ * @param[in] floor specifies the priority level immediately below
+ *     that at which events from tasks are not captured.
+ *
+ * @retval 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_capture_watch_floor (rtems_task_priority floor);
 
 /**
- * rtems_capture_watch_get_floor
- *
- *  DESCRIPTION:
+ * @brief Capture set watch floor
  *
  * This function gets the watch floor.
+ *
+ * @retval The priority level immediately below
+ *     that at which events from tasks are not captured.
  */
 rtems_task_priority
 rtems_capture_watch_get_floor (void);
 
 /**
- * rtems_capture_set_trigger
- *
- *  DESCRIPTION:
+ * @brief Capture set trigger
  *
  * This function sets a trigger.
  *
@@ -439,6 +482,21 @@ rtems_capture_watch_get_floor (void);
  * We can have a number of tasks that have the same name so we
  * search using names. This means a number of tasks can be
  * linked to single control.
+ *
+ * Some events captured such as context switch include two
+ * tasks. These are referred to as being "from" and "to"
+ * Some events may only have one task specified.
+ *
+ * @param[in] from_name specifies the name of the from task.
+ * @param[in] from_id specifies the id of the from task.
+ * @param[in] to_name specifies the name of the to task.
+ * @param[in] to_id specifies the id of the to task.
+ * @param[in] mode specifies the trigger mode.
+ * @param[in] trigger specifies the type of trigger.
+ *
+ * @retval 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_capture_set_trigger (rtems_name                   from_name,
@@ -449,13 +507,22 @@ rtems_capture_set_trigger (rtems_name                   from_name,
                            rtems_capture_trigger_t      trigger);
 
 /**
- * rtems_capture_clear_trigger
- *
- *  DESCRIPTION:
+ * @brief Capture clear trigger.
  *
  * This function clears a trigger.
  *
  * This clear trigger routine will not clear a watch.
+ *
+ * @param[in] from_name specifies the name of the from task.
+ * @param[in] from_id specifies the id of the from task.
+ * @param[in] to_name specifies the name of the to task.
+ * @param[in] to_id specifies the id of the to task.
+ * @param[in] mode specifies the trigger mode.
+ * @param[in] trigger specifies the type of trigger.
+ *
+ * @retval 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_capture_clear_trigger (rtems_name                   from_name,
@@ -466,9 +533,7 @@ rtems_capture_clear_trigger (rtems_name                   from_name,
                              rtems_capture_trigger_t      trigger);
 
 /**
- * rtems_capture_read
- *
- *  DESCRIPTION:
+ * @brief Capture read records from capture buffer
  *
  * This function reads a number of records from the capture buffer.
  * The user can optionally block and wait until the buffer as a
@@ -492,9 +557,17 @@ rtems_capture_clear_trigger (rtems_name                   from_name,
  * thrashing occuring for a small number of records, yet allows
  * a user configured latiency to be applied for single events.
  *
- * The 'timeout' parameter is in micro-seconds. A value of 0 will
+ * The @a timeout parameter is in microseconds. A value of 0 will
  * disable the timeout.
  *
+ * @param[in] threshold The number of records that must be captured 
+ * @param[in] timeout The micro-second timeout period
+ * @param[out] read will contain the number of records read
+ * @param[out] recs The capture records that are read.
+ *
+ * @retval 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_capture_read (uint32_t                 threshold,
@@ -503,56 +576,66 @@ rtems_capture_read (uint32_t                 threshold,
                     rtems_capture_record_t** recs);
 
 /**
- * rtems_capture_release
- *
- *  DESCRIPTION:
+ * @brief Capture release records.
  *
  * This function releases the requested number of record slots back
  * to the capture engine. The count must match the number read.
+ *
+ * @param[in] count The number of record slots to release
+ * 
+ * @retval 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_capture_release (uint32_t count);
 
 /*
- * rtems_capture_time
- *
- *  DESCRIPTION:
+ * @brief Capture nano-second time period.
  *
  * This function returns the time period in nano-seconds.
+ *
+ * @param[out] uptime The nano-second time period.
  */
 void
 rtems_capture_time (rtems_capture_time_t* uptime);
 
 /**
- * rtems_capture_event_text
- *
- *  DESCRIPTION:
+ * @brief Capture get event text.
  *
  * This function returns a string for an event based on the bit in the
  * event. The functions takes the bit offset as a number not the bit
  * set in a bit map.
+ *
+ * @param[in] event specifies the event to describe
+ *
+ * @retval This method returns a string description of the given event.
  */
 const char*
 rtems_capture_event_text (int event);
 
 /**
- * rtems_capture_get_task_list
- *
- *  DESCRIPTION:
+ * @brief Capture get task list.
  *
  * This function returns the head of the list of tasks that the
  * capture engine has detected.
+ *
+ * @retval  This function returns the head of the list of tasks that 
+ *          the capture engine has detected.
  */
 rtems_capture_task_t*
 rtems_capture_get_task_list (void);
 
 /**
- * rtems_capture_next_task
- *
- *  DESCRIPTION:
+ * @brief Capture get next task in list.
  *
  * This function returns the pointer to the next task in the list. The
  * pointer NULL terminates the list.
+ *
+ * @param[in] task The capture task to get the next entry from.
+ * 
+ * @retval This function returns the pointer to the next task in the list. The
+ * pointer NULL terminates the list.
  */
 static inline rtems_capture_task_t*
 rtems_capture_next_task (rtems_capture_task_t* task)
@@ -561,12 +644,15 @@ rtems_capture_next_task (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_valid
- *
- *  DESCRIPTION:
+ * @brief Capture is valid task control block
  *
  * This function returns true if the task control block points to
  * a valid task.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns true if the task control block points to
+ * a valid task. Otherwise, it returns false.
  */
 static inline bool
 rtems_capture_task_valid (rtems_capture_task_t* task)
@@ -575,11 +661,13 @@ rtems_capture_task_valid (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_id
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get task id.
+ * 
  * This function returns the task id.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the task id.
  */
 static inline rtems_id
 rtems_capture_task_id (rtems_capture_task_t* task)
@@ -588,11 +676,13 @@ rtems_capture_task_id (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_state
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get task state.
+ * 
  * This function returns the task state.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the task state.
  */
 static inline States_Control
 rtems_capture_task_state (rtems_capture_task_t* task)
@@ -603,11 +693,13 @@ rtems_capture_task_state (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_name
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get task name.
+ * 
  * This function returns the task name.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the task name.
  */
 static inline rtems_name
 rtems_capture_task_name (rtems_capture_task_t* task)
@@ -616,11 +708,13 @@ rtems_capture_task_name (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_flags
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get task flags.
+ * 
  * This function returns the task flags.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the task flags.
  */
 static inline uint32_t
 rtems_capture_task_flags (rtems_capture_task_t* task)
@@ -629,11 +723,13 @@ rtems_capture_task_flags (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_control
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get task control
+ * 
  * This function returns the task control if present.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the task control if present.
  */
 static inline rtems_capture_control_t*
 rtems_capture_task_control (rtems_capture_task_t* task)
@@ -642,11 +738,13 @@ rtems_capture_task_control (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_control_flags
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get task control flags.
+ * 
  * This function returns the task control flags if a control is present.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the task control flags if a control is present.
  */
 static inline uint32_t
 rtems_capture_task_control_flags (rtems_capture_task_t* task)
@@ -657,12 +755,15 @@ rtems_capture_task_control_flags (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_switched_in
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get number of times task switched in.
+ * 
  * This function returns the number of times the task has
  * been switched into context.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the number of times the task has
+ * been switched into context.
  */
 static inline uint32_t
 rtems_capture_task_switched_in (rtems_capture_task_t* task)
@@ -671,12 +772,15 @@ rtems_capture_task_switched_in (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_switched_out
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get number of times task switched out.
+ * 
  * This function returns the number of times the task has
  * been switched out of context.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the number of times the task has
+ * been switched out of context.
  */
 static inline uint32_t
 rtems_capture_task_switched_out (rtems_capture_task_t* task)
@@ -685,12 +789,15 @@ rtems_capture_task_switched_out (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_curr_priority
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get task start priority.
+ * 
  * This function returns the tasks start priority. The tracer needs this
  * to track where the task's priority goes.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the tasks start priority. The tracer needs this
+ * to track where the task's priority goes.
  */
 static inline rtems_task_priority
 rtems_capture_task_start_priority (rtems_capture_task_t* task)
@@ -699,11 +806,13 @@ rtems_capture_task_start_priority (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_real_priority
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get task real priority.
+ * 
  * This function returns the tasks real priority.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the tasks real priority.
  */
 static inline rtems_task_priority
 rtems_capture_task_real_priority (rtems_capture_task_t* task)
@@ -714,11 +823,13 @@ rtems_capture_task_real_priority (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_curr_priority
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get task current priority.
+ * 
  * This function returns the tasks current priority.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the tasks current priority.
  */
 static inline rtems_task_priority
 rtems_capture_task_curr_priority (rtems_capture_task_t* task)
@@ -729,22 +840,27 @@ rtems_capture_task_curr_priority (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_stack_usage
- *
- *  DESCRIPTION:
- *
+ * @brief Capture update stack usage.
+ * 
  * This function updates the stack usage. The task control block
  * is updated.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function updates the stack usage. The task control block
+ * is updated.
  */
 uint32_t
 rtems_capture_task_stack_usage (rtems_capture_task_t* task);
 
 /**
- * rtems_capture_task_stack_size
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get stack size.
+ * 
  * This function returns the task's stack size.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the task's stack size.
  */
 static inline uint32_t
 rtems_capture_task_stack_size (rtems_capture_task_t* task)
@@ -753,11 +869,13 @@ rtems_capture_task_stack_size (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_stack_used
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get stack used.
+ * 
  * This function returns the amount of stack used.
+ * 
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the amount of stack used.
  */
 static inline uint32_t
 rtems_capture_task_stack_used (rtems_capture_task_t* task)
@@ -766,11 +884,13 @@ rtems_capture_task_stack_used (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_time
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get task execution time.
+ * 
  * This function returns the current execution time.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the current execution time.
  */
 static inline uint64_t
 rtems_capture_task_time (rtems_capture_task_t* task)
@@ -779,12 +899,15 @@ rtems_capture_task_time (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_delta_time
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get delta in execution time.
+ * 
  * This function returns the execution time as a different between the
  * last time the detla time was and now.
+ *
+ * @param[in] task The capture task.
+ * 
+ * @retval This function returns the execution time as a different between the
+ * last time the detla time was and now.
  */
 static inline uint64_t
 rtems_capture_task_delta_time (rtems_capture_task_t* task)
@@ -795,12 +918,13 @@ rtems_capture_task_delta_time (rtems_capture_task_t* task)
 }
 
 /**
- * rtems_capture_task_count
- *
- *  DESCRIPTION:
+ * @brief Capture get task count.
  *
  * This function returns the number of tasks the capture
  * engine knows about.
+ *
+ * @retval This function returns the number of tasks the capture
+ * engine knows about.
  */
 static inline uint32_t
 rtems_capture_task_count (void)
@@ -818,23 +942,27 @@ rtems_capture_task_count (void)
 }
 
 /**
- * rtems_capture_get_control_list
- *
- *  DESCRIPTION:
+ * @brief Capture get control list.
  *
  * This function returns the head of the list of controls in the
  * capture engine.
+ *
+ * @retval This function returns the head of the list of controls in the
+ * capture engine.
  */
 rtems_capture_control_t*
 rtems_capture_get_control_list (void);
 
 /**
- * rtems_capture_next_control
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get next capture control.
+ * 
  * This function returns the pointer to the next control in the list. The
  * pointer NULL terminates the list.
+ *
+ * @param[in] control the current capture control.
+ * 
+ * @retval This function returns the pointer to the next control in the list. The
+ * pointer NULL terminates the list.
  */
 static inline rtems_capture_control_t*
 rtems_capture_next_control (rtems_capture_control_t* control)
@@ -843,11 +971,13 @@ rtems_capture_next_control (rtems_capture_control_t* control)
 }
 
 /**
- * rtems_capture_control_id
- *
- *  DESCRIPTION:
- *
+ * @brief Capture get capture control id.
+ * 
  * This function returns the control id.
+ *
+ * @param[in] control the capture control.
+ * 
+ * @retval This function returns the control id.
  */
 static inline rtems_id
 rtems_capture_control_id (rtems_capture_control_t* control)
@@ -856,11 +986,13 @@ rtems_capture_control_id (rtems_capture_control_t* control)
 }
 
 /**
- * rtems_capture_control_name
- *
- *  DESCRIPTION:
+ * @brief Capture get capture control name.
  *
  * This function returns the control name.
+ *
+ * @param[in] control the capture control.
+ *
+ * @retval This function returns the control name.
  */
 static inline rtems_name
 rtems_capture_control_name (rtems_capture_control_t* control)
@@ -869,11 +1001,13 @@ rtems_capture_control_name (rtems_capture_control_t* control)
 }
 
 /**
- * rtems_capture_control_flags
- *
- *  DESCRIPTION:
+ * @brief Capture get capture control flags.
  *
  * This function returns the control flags.
+ *
+ * @param[in] control the capture control.
+ *
+ * @retval This function returns the control flags.
  */
 static inline uint32_t
 rtems_capture_control_flags (rtems_capture_control_t* control)
@@ -882,11 +1016,13 @@ rtems_capture_control_flags (rtems_capture_control_t* control)
 }
 
 /**
- * rtems_capture_control_to_triggers
- *
- *  DESCRIPTION:
+ * @brief Capture get capture control to triggers.
  *
  * This function returns the task control to triggers.
+ *
+ * @param[in] control the capture control.
+ *
+ * @retval This function returns the task control to triggers.
  */
 static inline uint32_t
 rtems_capture_control_to_triggers (rtems_capture_control_t* control)
@@ -895,11 +1031,13 @@ rtems_capture_control_to_triggers (rtems_capture_control_t* control)
 }
 
 /**
- * rtems_capture_control_from_triggers
- *
- *  DESCRIPTION:
+ * @brief Capture get capture control from triggers.
  *
  * This function returns the task control from triggers.
+ *
+ * @param[in] control the capture control.
+ *
+ * @retval This function returns the task control from triggers.
  */
 static inline uint32_t
 rtems_capture_control_from_triggers (rtems_capture_control_t* control)
@@ -908,11 +1046,13 @@ rtems_capture_control_from_triggers (rtems_capture_control_t* control)
 }
 
 /**
- * rtems_capture_control_all_by_triggers
- *
- *  DESCRIPTION:
+ * @brief Capture get capture control by triggers.
  *
  * This function returns the task control by triggers.
+ *
+ * @param[in] control the capture control.
+ *
+ * @retval This function returns the task control by triggers.
  */
 static inline uint32_t
 rtems_capture_control_all_by_triggers (rtems_capture_control_t* control)
@@ -921,11 +1061,14 @@ rtems_capture_control_all_by_triggers (rtems_capture_control_t* control)
 }
 
 /**
- * rtems_capture_control_by_valid
- *
- *  DESCRIPTION:
+ * @brief Capture get capture control valid by flags.
  *
  * This function returns the control valid BY flags.
+ *
+ * @param[in] control The capture control.
+ * @param[in] slot The XXX.
+ *
+ * @retval This function returns the control valid BY flags.
  */
 static inline int
 rtems_capture_control_by_valid (rtems_capture_control_t* control, int slot)
@@ -934,11 +1077,14 @@ rtems_capture_control_by_valid (rtems_capture_control_t* control, int slot)
 }
 
 /**
- * rtems_capture_control_by_name
+ * @brief Capture get capture control by task name.
  *
- *  DESCRIPTION:
+ * This function returns the control @a by task name.
  *
- * This function returns the control BY task name.
+ * @param[in] control The capture control.
+ * @param[in] by The XXX.
+ *
+ * @retval This function returns the control @a by task name.
  */
 static inline rtems_name
 rtems_capture_control_by_name (rtems_capture_control_t* control, int by)
@@ -949,11 +1095,11 @@ rtems_capture_control_by_name (rtems_capture_control_t* control, int by)
 }
 
 /**
- * rtems_capture_control_by_id
- *
- *  DESCRIPTION:
+ * @brief Capture get capture control by task id.
  *
- * This function returns the control BY task id.
+ * This function returns the control @a by task id
+ * 
+ * @retval This function returns the control @a by task id.
  */
 static inline rtems_id
 rtems_capture_control_by_id (rtems_capture_control_t* control, int by)
@@ -964,11 +1110,11 @@ rtems_capture_control_by_id (rtems_capture_control_t* control, int by)
 }
 
 /**
- * rtems_capture_control_by_triggers
+ * @brief Capture get capture control by task triggers.
  *
- *  DESCRIPTION:
+ * This function returns the control @a by task triggers.
  *
- * This function returns the control BY task triggers.
+ * @retval This function returns the control @a by task triggers.
  */
 static inline uint32_t
 rtems_capture_control_by_triggers (rtems_capture_control_t* control,
@@ -980,12 +1126,13 @@ rtems_capture_control_by_triggers (rtems_capture_control_t* control,
 }
 
 /**
- * rtems_capture_control_count
- *
- *  DESCRIPTION:
+ * @brief Capture get capture control count.
  *
  * This function returns the number of controls the capture
  * engine has.
+ *
+ * @retval This function returns the number of controls the capture
+ * engine has.
  */
 static inline uint32_t
 rtems_capture_control_count (void)