1 files changed, 23 insertions, 13 deletions
diff --git a/docs/src/main.dox b/docs/src/main.dox
index 0013737df..e1852342e 100644
--- a/docs/src/main.dox
+++ b/docs/src/main.dox
@@ -272,20 +272,30 @@
  */
 
 /**
- * @defgroup Events Events
- * Event Sources and Event Listeners.
+ * @defgroup Events Event Flags
+ * @brief Event Flags, Event Sources and Event Listeners.
  * <h2>Operation mode</h2>
- * An Event Source is a special object that can be signaled by a thread or
- * an interrupt service routine. Signaling an Event Source has the effect
- * that all the threads registered on the Event Source will receive
- * and serve the event.<br>
+ * Each thread has a mask of pending event flags inside its Thread structure.
+ * Several operations are defined:
+ * - <b>Wait</b>, the invoking thread goes to sleep until a certain AND/OR
+ *   combination of event flags becomes pending.
+ * - <b>Clear</b>, a mask of event flags is cleared from the pending events
+ *   mask, the cleared event flags mask is returned (only the flags that were
+     actually pending and then cleared).
+ * - <b>Signal</b>, an event mask is directly ORed to the mask of the signaled
+ *   thread.
+ * - <b>Broadcast</b>, each thread registered on an Event Source is signaled
+ *   with the event flags specified in its Event Listener.
+ * - <b>Dispatch</b>, an events mask is scanned and for each bit set to one
+ *   an associated handler function is invoked. Bit masks are scanned from bit
+ *   zero upward.
+ * .
+ * An Event Source is a special object that can be "broadcasted" by a thread or
+ * an interrupt service routine. Broadcasting an Event Source has the effect
+ * that all the threads registered on the Event Source will be signaled with
+ * and events mask.<br>
  * An unlimited number of Event Sources can exists in a system and each
- * thread can listen on an unlimited number of them.<br>
- * Note that the events can be asynchronously generated but are synchronously
- * served, a thread can serve event by calling a @p chEvtWaitXXX()
- * API. If an event is generated while a listening thread is not ready to
- * serve it then the event becomes "pending" and will be served as soon the
- * thread invokes a @p chEvtWaitXXX().<br>
+ * thread can listen on an unlimited number of them.<br><br>
  * In order to use the Event APIs the @p CH_USE_EVENTS option must be
  * specified in @p chconf.h.
  * @ingroup Synchronization
@@ -295,7 +305,7 @@
  * @defgroup Messages Synchronous Messages
  * Synchronous inter-thread messages.
  * <h2>Operation Mode</h2>
- * Synchronoud messages are an easy to use and fast IPC mechanism, threads
+ * Synchronous messages are an easy to use and fast IPC mechanism, threads
  * can both serve messages and send messages to other threads, the mechanism
  * allows data to be carried in both directions. Data is not copied between
  * the client and server threads but just a pointer passed so the exchange