Edit

events/README.md

@@ -1,42 +1,35 @@
-## The mbed-events library ##
+# The mbed-events library
 
-The mbed-events library provides a flexible queue for scheduling events.
+The mbed-events library provides a flexible queue for scheduling events. It can be used as a normal event loop, or it can be backgrounded on a single hardware timer or even another event loop. It is both thread and IRQ safe, and provides functions for easily composing independent event queues.
+
+The library can act as a drop-in scheduler, provide synchronization between multiple threads, or just act as a mechanism for moving events out of interrupt contexts.
+
+## Example
 
 ``` cpp
 #include "mbed_events.h"
 #include <stdio.h>
 
 int main() {
-    // creates a queue with the default size
+    // Creates a queue with the default size
     EventQueue queue;
 
-    // events are simple callbacks
+    // Events are simple callbacks
     queue.call(printf, "called immediately\n");
     queue.call_in(2000, printf, "called in 2 seconds\n");
     queue.call_every(1000, printf, "called every 1 seconds\n");
 
-    // events are executed by the dispatch method
+    // Events are executed by the dispatch method
     queue.dispatch();
 }
 ```
 
-The mbed-events library can be used as a normal event loop, or it can be
-backgrounded on a single hardware timer or even another event loop. It is
-both thread and irq safe, and provides functions for easily composing 
-independent event queues.
-
-The mbed-events library can act as a drop-in scheduler, provide synchronization
-between multiple threads, or just act as a mechanism for moving events out of 
-interrupt contexts.
-
-### Usage ###
+## Usage
 
-The core of the mbed-events library is the [EventQueue](EventQueue.h) class,
-which represents a single event queue. The `EventQueue::dispatch` function
-runs the queue, providing the context for executing events.
+The core of the mbed-events library is the [EventQueue](https://docs.mbed.com/docs/mbed-os-api/en/mbed-os-5.2/api/classevents_1_1EventQueue.html) class, which represents a single event queue. The `EventQueue::dispatch` function runs the queue, providing the context for executing events:
 
 ``` cpp
-// Creates an event queue enough buffer space for 32 Callbacks. This
+// Creates an event queue with enough buffer space for 32 Callbacks. This
 // is the default if no argument was provided. Alternatively the size
 // can just be specified in bytes.
 EventQueue queue(32*EVENTS_EVENT_SIZE);
@@ -46,16 +39,13 @@ EventQueue queue(32*EVENTS_EVENT_SIZE);
 queue.call(printf, "hello %d %d %d %d\n", 1, 2, 3, 4);
 queue.call(&serial, &Serial::printf, "hi\n");
 
-// The dispatch function provides the context for the running the queue
+// The dispatch function provides the context for running the queue
 // and can take a millisecond timeout to run for a fixed time or to just
 // dispatch any pending events
 queue.dispatch();
 ```
 
-The EventQueue class provides several call functions for posting events
-to the underlying event queue. The call functions are thread and irq safe,
-don't need the underlying loop to be running, and provide an easy mechanism
-for moving events out of interrupt contexts.
+The EventQueue class provides several call functions for posting events to the underlying event queue. The call functions are thread and IRQ safe, don't need the underlying loop to be running, and provide an easy mechanism for moving events out of interrupt contexts:
 
 ``` cpp
 // Simple call function registers events to be called as soon as possible
@@ -73,16 +63,14 @@ queue.call_every(2000, doit_every_two_seconds);
 queue.call_every(400, printf, "called every 0.4 seconds\n");
 ```
 
-The call functions return an id that uniquely represents the event in the 
-the event queue. This id can be passed to `EventQueue::cancel` to cancel
-an in-flight event.
+The call functions return an ID that uniquely represents the event in the event queue. This ID can be passed to `EventQueue::cancel` to cancel an in-flight event:
 
 ``` cpp
-// The event id uniquely represents the event in the queue
+// The event ID uniquely represents the event in the queue
 int id = queue.call_in(100, printf, "will this work?\n");
 
 // If there was not enough memory necessary to allocate the event,
-// an id of 0 is returned from the call functions
+// an ID of 0 is returned from the call functions
 if (id) {
     error("oh no!");
 }
@@ -92,10 +80,7 @@ if (id) {
 queue.cancel(id);
 ```
 
-For a more fine-grain control of event dispatch, the `Event` class can be
-manually instantiated and configured. An `Event` represents an event as
-a C++ style function object and can be directly passed to other APIs that
-expect a callback.
+For a more fine-grain control of event dispatch, the `Event` class can be manually instantiated and configured. An `Event` represents an event as a C++ style function object and can be directly passed to other APIs that expect a callback:
 
 ``` cpp
 // Creates an event bound to the specified event queue
@@ -112,7 +97,7 @@ event.period(10000);
 queue.dispatch();
 
 // Events can also pass arguments to the underlying callback when both
-// initially constructed and posted.
+// are initially constructed and posted.
 Event<void(int, int)> event(&queue, printf, "recieved %d and %d\n");
 
 // Events can be posted multiple times and enqueue gracefully until
@@ -124,10 +109,7 @@ event.post(5, 6);
 queue.dispatch();
 ```
 
-Event queues easily align with module boundaries, where internal state can
-be implicitly synchronized through event dispatch. Multiple modules can
-use independent event queues, but still be composed through the
-`EventQueue::chain` function.
+Event queues easily align with module boundaries, where internal state can be implicitly synchronized through event dispatch. Multiple modules can use independent event queues, but still be composed through the `EventQueue::chain` function:
 
 ``` cpp
 // Create some event queues with pending events