Merge pull request #14438 from Eric-A-Marks/master

Update Event Queue Documentation

Author: adbridge

events/README.md

@@ -75,7 +75,7 @@ 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. You can pass this ID to `EventQueue::cancel` to cancel
-an in-flight event.
+an in-flight event prior to dispatch.
 
 ``` cpp
 // The event id uniquely represents the event in the queue
@@ -88,7 +88,7 @@ if (id) {
 }
 
 // Events can be cancelled as long as they have not been dispatched. If the
-// event has already expired, cancel has no side-effects.
+// event has already expired, cancel may have negative side-effects.
 queue.cancel(id);
 ```
 
@@ -192,7 +192,7 @@ out of interrupt contexts.
 ## Documentation ##
 
 The in-depth documentation on specific functions can be found in
-[equeue.h](equeue.h).
+[equeue.h](include/events/equeue.h).
 
 The core of the equeue library is the `equeue_t` type which represents a
 single event queue, and the `equeue_dispatch` function which runs the equeue,
@@ -257,7 +257,7 @@ int enet_consume(void *buffer, int size) {
 ```
 
 Additionally, in-flight events can be cancelled with `equeue_cancel`. Events
-are given unique ids on post, allowing safe cancellation of expired events.
+are given unique ids on post, allowing safe cancellation until dispatch.
 
 ``` c
 #include "equeue.h"

events/include/events/Event.h

@@ -228,7 +228,7 @@ class Event<void(ArgTs...)> {
 
     /** Cancels the most recently posted event
      *
-     *  Attempts to cancel the most recently posted event. It is safe to call
+     *  Attempts to cancel the most recently posted event. It is not safe to call
      *  cancel after an event has already been dispatched.
      *
      *  The cancel function is IRQ safe.

events/include/events/EventQueue.h

@@ -154,7 +154,7 @@ class EventQueue : private mbed::NonCopyable<EventQueue> {
     /** Cancel an in-flight event
      *
      *  Attempts to cancel an event referenced by the unique id returned from
-     *  one of the call functions. It is safe to call cancel after an event
+     *  one of the call functions. It is not safe to call cancel after an event
      *  has already been dispatched.
      *
      *  id must be valid i.e. event must have not finished executing.
@@ -175,7 +175,7 @@ class EventQueue : private mbed::NonCopyable<EventQueue> {
     /** Cancel an in-flight user allocated event
      *
      *  Attempts to cancel an UserAllocatedEvent referenced by its address
-     *  It is safe to call cancel after an event has already been dispatched.
+     *  It is not safe to call cancel after an event has already been dispatched.
      *
      *  Event must be valid i.e. event must have not finished executing
      *  and must have been bound to this queue.

events/include/events/UserAllocatedEvent.h

@@ -230,7 +230,7 @@ class UserAllocatedEvent<F, void(ArgTs...)> {
 
     /** Cancels posted event
      *
-     *  Attempts to cancel posted event. It is safe to call
+     *  Attempts to cancel posted event. It is not safe to call
      *  cancel after an event has already been dispatched.
      *
      *  The cancel function is IRQ safe.

events/include/events/equeue.h

@@ -195,7 +195,7 @@ void equeue_post_user_allocated(equeue_t *queue, void (*cb)(void *), void *event
 // Cancel an in-flight event
 //
 // Attempts to cancel an event referenced by the unique id returned from
-// equeue_call or equeue_post. It is safe to call equeue_cancel after an event
+// equeue_call or equeue_post. It is not safe to call equeue_cancel after an event
 // has already been dispatched.
 //
 // The equeue_cancel function is irq safe.
@@ -210,14 +210,14 @@ bool equeue_cancel(equeue_t *queue, int id);
 // Cancel an in-flight user allocated event
 //
 // Attempts to cancel an event referenced by its address.
-// It is safe to call equeue_cancel_user_allocated after an event
+// It is not safe to call equeue_cancel_user_allocated after an event
 // has already been dispatched.
 //
 // The equeue_cancel_user_allocated function is irq safe.
 //
 // If called while the event queue's dispatch loop is active,
 // equeue_cancel_user_allocated does not guarantee that the event
-// will not not execute after it returns as the event may have
+// will not execute after it returns as the event may have
 // already begun executing.
 bool equeue_cancel_user_allocated(equeue_t *queue, void *event);