Improve docs

2 files changed, 35 insertions, 20 deletions

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index a4c5438a08..944e9ab13b 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -583,6 +583,20 @@ handle_event(_, _, State, Data) ->
 	  <seealso marker="#Module:callback_mode/0"><c>Module:callback_mode/0</c></seealso>
 	  does not return such a list, no state entry events are inserted.
 	</p>
+	<p>
+	  No state entry event will be inserted after a
+	  <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso>
+	  since transforming the state to a newer version is regarded
+	  as staying in the same state even if the newer version state
+	  should have a different name.
+	</p>
+	<p>
+	  Note that a state entry event <em>will</em> be inserted
+	  when entering the initial state even though this formally
+	  is not a state change.  In this case <c>OldState</c>
+	  will be the same as <c>State</c>, which can not happen
+	  for an actual state change.
+	</p>
       </desc>
     </datatype>
     <datatype>
@@ -1335,7 +1349,7 @@ handle_event(_, _, State, Data) ->
 	  CallbackMode =
 	  <seealso marker="#type-callback_mode">callback_mode()</seealso> |
 	  [ <seealso marker="#type-callback_mode">callback_mode()</seealso>
-	  | state_entry_events ]
+	  | <seealso marker="#type-state_entry_mode"><c>state_entry_events</c></seealso> ]
 	</v>
       </type>
       <desc>
@@ -1368,23 +1382,6 @@ handle_event(_, _, State, Data) ->
 	  and possibly the atom
 	  <seealso marker="#type-state_entry_mode"><c>state_entry_events</c></seealso>.
 	</p>
-	<p>
-	  If the atom <c>state_entry_events</c> is present in the list,
-	  the <c>gen_statem</c> engine will, at every state change,
-	  insert an event of type
-	  <seealso marker="#type-event_type">enter</seealso>
-	  with content <c>OldState</c>.  This event will be inserted
-	  before all other events such as those generated by
-	  <seealso marker="#type-action"><c>action()</c></seealso>
-	  <c>next_event</c>.
-	</p>
-	<p>
-	  No state entry event will be inserted after a
-	  <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso>
-	  since transforming the state to a newer version is regarded
-	  as staying in the same state even if the newer version state
-	  should have a different name.
-	</p>
 	<note>
 	  <p>
 	    If this function's body does not return an inline constant
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index 8090016b54..43359829b2 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -989,7 +989,17 @@ do_unlock() ->
       from your state machine to itself.
     </p>
     <p>
-      One example of using self-generated events can be when you have
+      One example for this is to pre-process incoming data, for example
+      decrypting chunks or collecting characters up to a line break.
+      This could be modelled with a separate state machine that sends
+      the pre-processed events to the main state machine, or to decrease
+      overhead the small pre-processing state machine can be implemented
+      in the common state event handling of the main state machine
+      using a few state data variables and then send the pre-processed
+      events as internal events to the main state machine.
+    </p>
+    <p>
+      Another example of using self-generated events can be when you have
       a state machine specification that uses state entry actions.
       You can code that using a dedicated function
       to do the state transition. But if you want that code to be
@@ -1050,7 +1060,15 @@ enter(Tag, State, Data) ->
       <seealso marker="#state_entry_events">state entry events</seealso>.
       You will have to handle the state entry events in every state.
       If you want state entry code in just a few states the previous
-      example may be more suitable.
+      example may be more suitable, especially to only send internal
+      events when entering just those few states.
+    </p>
+    <p>
+      You can also in the previous example choose to generate
+      events looking just like the events you get from using
+      <seealso marker="#state_entry_events">state entry events</seealso>.
+      This may be confusing, or practical,
+      depending on your point of view.
     </p>
     <code type="erl"><![CDATA[
 ...