Merge branch 'maint'

* maint:
  Mention action handling details in user's guide
  Clarify handling of Actions

2 files changed, 53 insertions, 28 deletions

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index ef548ad643..5513b7d649 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -720,7 +720,9 @@ handle_event(_, _, State, Data) ->
 	  the <c>gen_statem</c> engine will, at every <em>state change</em>,
 	  call the
 	  <seealso marker="#state callback">state callback</seealso>
-	  with arguments <c>(enter, OldState, Data)</c>.
+	  with arguments <c>(enter, OldState, Data)</c> or
+	  <c>(enter, OldState, State, Data)</c>, depending on the
+	  <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>.
 	  This may look like an event but is really a call
 	  performed after the previous
 	  <seealso marker="#state callback"><em>state callback</em></seealso>
@@ -776,44 +778,53 @@ handle_event(_, _, State, Data) ->
 	</p>
 	<list type="ordered">
 	  <item>
+	    <p>
+	      All returned
+              <seealso marker="#type-action">actions</seealso>
+	      are processed in order of appearance.
+	      In this step all replies generated by any
+	      <seealso marker="#type-reply_action"><c>reply_action()</c></seealso>
+	      are sent.  Other actions set <c>transition_option()</c>s
+	      that come into play in subsequent steps.
+            </p>
+	  </item>
+	  <item>
             <p>
 	      If
 	      <seealso marker="#type-state_enter">
 		<em>state enter calls</em>
 	      </seealso>
-	      are used, and either:
-	      the state changes, it is the initial state,
-	      or one of the callback results
+	      are used, and either
+	      it is the initial state or one of the callback results
 	      <seealso marker="#type-state_callback_result">
-		<c>repeat_state</c>
+		<c>repeat_state_and_data</c>
 	      </seealso>
 	      or
 	      <seealso marker="#type-state_callback_result">
 		<c>repeat_state_and_data</c>
 	      </seealso>
-	      is used; the <c>gen_statem</c> calls
-	      the new state callback with arguments
-	      <seealso marker="#type-state_enter"><c>(enter, OldState, Data)</c></seealso>.
+	      is used the <c>gen_statem</c> engine calls
+	      the current state callback with arguments
+	      <seealso marker="#type-state_enter"><c>(enter, State, Data)</c></seealso>
+	      or
+	      <seealso marker="#type-state_enter"><c>(enter, State, State, Data)</c></seealso>
+	      (depending on <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>)
+	      and when it returns starts again from the top of this sequence.
 	    </p>
-	    <p>
-	      Any 
-	      <seealso marker="#type-enter_action">actions</seealso>
-	      returned from this call are handled as if they were
-	      appended to the actions
-	      returned by the state callback that caused the state entry.
+            <p>
+	      If
+	      <seealso marker="#type-state_enter">
+		<em>state enter calls</em>
+	      </seealso>
+	      are used, and the state changes
+	      the <c>gen_statem</c> engine calls
+	      the new state callback with arguments
+	      <seealso marker="#type-state_enter"><c>(enter, OldState, Data)</c></seealso>
+	      or
+	      <seealso marker="#type-state_enter"><c>(enter, OldState, State, Data)</c></seealso>
+	      (depending on <seealso marker="#type-callback_mode"><em>callback mode</em></seealso>)
+	      and when it returns starts again from the top of this sequence.
 	    </p>
-	    <p>
-	      Should this <em>state enter call</em> return any of
-	      the mentioned <c>repeat_*</c> callback results
-	      it is repeated again, with the updated <c>Data</c>.
-            </p>
-	  </item>
-	  <item>
-	    <p>
-	      All
-              <seealso marker="#type-action">actions</seealso>
-	      are processed in order of appearance.
-            </p>
 	  </item>
 	  <item>
             <p>
@@ -863,7 +874,9 @@ handle_event(_, _, State, Data) ->
 	      A <em>state change</em> cancels a
               <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso>
 	      and any new transition option of this type
-	      belongs to the new state.
+	      belongs to the new state, that is; a
+              <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso>
+	      applies to the state the state machine enters.
 	    </p>
 	  </item>
 	  <item>
@@ -872,7 +885,7 @@ handle_event(_, _, State, Data) ->
 	      <seealso marker="#state callback"><em>state callback</em></seealso>
 	      for the possibly new state
 	      is called with the oldest enqueued event,
-	      and we start again from the top of this list.
+	      and we start again from the top of this sequence.
 	    </p>
 	  </item>
 	  <item>
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index 23e9054547..81a0c617f1 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -624,6 +624,18 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
       and set a time-out to use absolute instead of relative time
       (using the <c>Opts</c> field).
     </p>
+    <p>
+      Among these <em>transition actions</em> only to reply to a caller
+      is an immediate action.  The others are collected and handled
+      later during the <em>state transition</em>.
+      <seealso marker="#Inserted Events">Inserted Events</seealso>
+      are stored and inserted all together,
+      and the rest set transition options
+      where the last of a specific type override the previous.
+      See the description of a <em>state transition</em>
+      in the <c>gen_statem(3)</c> manual page for type
+      <seealso marker="stdlib:gen_statem#type-transition_option"><c>transition_option()</c></seealso>.
+    </p>
   </section>
 
 <!-- =================================================================== -->