[rtems commit] rtems: Update event documentation

[Sebastian Huber]

Module:    rtems
Branch:    master
Commit:    134fc76d3b306e3627cefc612a269aa3e04ee9f8
Changeset: http://git.rtems.org/rtems/commit/?id=134fc76d3b306e3627cefc612a269aa3e04ee9f8

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Wed Oct 14 11:30:19 2020 +0200

rtems: Update event documentation

---

 cpukit/include/rtems/rtems/eventdata.h |  6 +++
 cpukit/include/rtems/rtems/eventimpl.h | 86 +++++++++++++++++++++++++++++-----
 2 files changed, 79 insertions(+), 13 deletions(-)

diff --git a/cpukit/include/rtems/rtems/eventdata.h b/cpukit/include/rtems/rtems/eventdata.h
index fa69a2a..23f0a1b 100644
--- a/cpukit/include/rtems/rtems/eventdata.h
+++ b/cpukit/include/rtems/rtems/eventdata.h
@@ -30,7 +30,13 @@ extern "C" {
  * @{
  */
 
+/**
+ * @brief This structure is used to manage a set of events.
+ */
 typedef struct {
+  /**
+   * @brief The member contains the pending events.
+   */
   rtems_event_set pending_events;
 } Event_Control;
 
diff --git a/cpukit/include/rtems/rtems/eventimpl.h b/cpukit/include/rtems/rtems/eventimpl.h
index dc56ad2..4635d76 100644
--- a/cpukit/include/rtems/rtems/eventimpl.h
+++ b/cpukit/include/rtems/rtems/eventimpl.h
@@ -25,13 +25,42 @@ extern "C" {
 #endif
 
 /**
- * @defgroup ClassicEventImpl Classic Event Implementation
+ * @defgroup ClassicEventImpl Event Implementation
  *
  * @ingroup RTEMSImplClassic
  *
  * @{
  */
 
+/**
+ * @brief Seizes a set of events.
+ *
+ * @param event_in is the input event set.
+ *
+ * @param option_set is the option set.
+ *
+ * @param ticks is the optional timeout in clock ticks.
+ *
+ * @param event_out[out] is the output event set.
+ *
+ * @param executing[in, out] is the executing thread.
+ *
+ * @param event[in, out] is the source event set.
+ *
+ * @param wait_class is the thread wait class of the source event set.
+ *
+ * @param block_state is the thread blocking state of the source event set.
+ *
+ * @param lock_context[in, out] is the lock context set up by _Thread_Get().
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_UNSATISFIED The events of interest were not immediately
+ *   available.
+ *
+ * @retval ::RTEMS_TIMEOUT The events of interest were not available within the
+ *   specified timeout interval.
+ */
 rtems_status_code _Event_Seize(
   rtems_event_set    event_in,
   rtems_option       option_set,
@@ -44,6 +73,21 @@ rtems_status_code _Event_Seize(
   ISR_lock_Context  *lock_context
 );
 
+/**
+ * @brief Surrenders a set of events.
+ *
+ * @param the_thread[in, out] is the thread of the event set.
+ *
+ * @param event_in is the set of events to post.
+ *
+ * @param event[in, out] is the target event set.
+ *
+ * @param wait_class is the thread wait class of the target event set.
+ *
+ * @param lock_context[in, out] is the lock context set up by _Thread_Get().
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ */
 rtems_status_code _Event_Surrender(
   Thread_Control    *the_thread,
   rtems_event_set    event_in,
@@ -52,16 +96,23 @@ rtems_status_code _Event_Surrender(
   ISR_lock_Context  *lock_context
 );
 
+/**
+ * @brief Initializes an event control block to have no pending events.
+ *
+ * @param event is the event control block to initialize.
+ */
 RTEMS_INLINE_ROUTINE void _Event_Initialize( Event_Control *event )
 {
   event->pending_events = 0;
 }
 
 /**
- *  @brief Checks if on events are posted in the event_set.
+ * @brief Checks if the event set is empty.
+ *
+ * @param the_event_set is the event set to check.
  *
- *  This function returns TRUE if on events are posted in the event_set,
- *  and FALSE otherwise.
+ * @return Returns true, if there are no posted events in the event set,
+ *   otherwise false.
  */
 RTEMS_INLINE_ROUTINE bool _Event_sets_Is_empty(
   rtems_event_set the_event_set
@@ -71,10 +122,11 @@ RTEMS_INLINE_ROUTINE bool _Event_sets_Is_empty(
 }
 
 /**
- *  @brief Posts the given new_events into the event_set passed in.
+ * @brief Posts the events in the specified event set.
  *
- *  This routine posts the given new_events into the event_set
- *  passed in.  The result is returned to the user in event_set.
+ * @param the_new_events is the set of events to post.
+ *
+ * @param the_event_set[in, out] is the event set.
  */
 RTEMS_INLINE_ROUTINE void _Event_sets_Post(
   rtems_event_set  the_new_events,
@@ -85,10 +137,14 @@ RTEMS_INLINE_ROUTINE void _Event_sets_Post(
 }
 
 /**
- *  @brief Returns the events in event_condition that are set in event_set.
+ * @brief Gets the events of the specified event condition.
+ *
+ * @param the_event_set is the event set.
  *
- *  This function returns the events in event_condition which are
- *  set in event_set.
+ * @param the_event_condition is the event condition defining the events of interest.
+ *
+ * @return Return the events of the event condition which are posted in the
+ *   event set.
  */
 RTEMS_INLINE_ROUTINE rtems_event_set _Event_sets_Get(
   rtems_event_set the_event_set,
@@ -99,10 +155,14 @@ RTEMS_INLINE_ROUTINE rtems_event_set _Event_sets_Get(
 }
 
 /**
- *  @brief Removes the events in mask from the event_set passed in.
+ * @brief Clears a set of events from an event set.
+ *
+ * @param the_event_set is the event set.
+ *
+ * @param the_mask is the set of events to clear.
  *
- *  This function removes the events in mask from the event_set
- *  passed in.  The result is returned to the user in event_set.
+ * @return Returns the event set with all event cleared specified by the event
+ *   mask.
  */
 RTEMS_INLINE_ROUTINE rtems_event_set _Event_sets_Clear(
  rtems_event_set the_event_set,