From 63b291070d5522b5b116c8fe158497ee55149656 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 25 Feb 2016 15:45:32 +0100
Subject: Clarify documentation after Torben Hoffman's comments

---
 lib/stdlib/doc/src/gen_statem.xml | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 35b842c173..4af6732e7c 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -374,7 +374,7 @@ erlang:'!'            -----> Module:StateName/3
 	  When used in the
 	  <seealso marker="#type-action">action()</seealso>
 	  <c>{remove_event,RemoveEventPredicate}</c>,
-	  the event for which the predicate returns <c>true</c>
+	  the oldest event for which the predicate returns <c>true</c>
 	  will be removed.
 	</p>
 	<p>
@@ -441,6 +441,14 @@ erlang:'!'            -----> Module:StateName/3
 	    If the state changes the queue of incoming events
             is reset to start with the oldest postponed.
 	  </item>
+	  <item>
+	    All events inserted with
+	    <seealso marker="#type-action">
+	      <c>action() next_event</c>
+	    </seealso>
+	    are inserted in the queue to be processed before
+	    all other events.
+	  </item>
 	  <item>
 	    If the
             <seealso marker="#type-postpone">
@@ -450,7 +458,8 @@ erlang:'!'            -----> Module:StateName/3
 	      <c>timeout</c>
 	    </seealso>
 	    is set a state timer may be started or a timeout zero event
-	    may be enqueued as the newest incoming.
+	    may be enqueued as the newest incoming that is the last
+	    to process before going into <c>receive</c> for new events.
 	  </item>
 	  <item>
 	    The (possibly new)
@@ -582,16 +591,16 @@ erlang:'!'            -----> Module:StateName/3
 	    and <c><anno>EventContent</anno></c> as the next to process.
 	    This will bypass any events in the process mailbox as well
 	    as any other queued events.
+	    All <c>next_event</c> actions
+	    in the containing list are buffered and inserted
+	    after the actions have been done
+	    so the first in the list will be the first to process.
 	    An event of type
 	    <seealso marker="#type-event_type">
 	      <c>internal</c>
 	    </seealso>
 	    should be used when you want to reliably distinguish
 	    an event inserted this way from any external event.
-	    If there are multiple <c>next_event</c> actions
-	    in the containing list they are buffered and all are
-	    inserted so the first in the list will be the
-	    first to process.
 	  </item>
 	  <tag><c>remove_event</c></tag>
 	  <item>
@@ -599,7 +608,11 @@ erlang:'!'            -----> Module:StateName/3
 	    that matches equal to <c><anno>EventType</anno></c>
 	    and <c><anno>EventContent</anno></c> or for which
 	    <c><anno>EventPredicate</anno></c>
-	    returns <c>true</c>.
+	    returns <c>true</c>.  Note that <c>next_event</c>
+	    and <c>postpone</c> events in the same actions list
+	    does not get into the event queue until after all actions
+	    has been done so you can not remove an event that you insert
+	    in the same actions list.  Make up your mind!
 	  </item>
 	  <tag><c>cancel_timer</c></tag>
 	  <item>
-- 
cgit v1.2.3