From 4ebdabdca2c964887115f21405993f3916843d10 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 16 Sep 2016 10:15:22 +0200
Subject: Improve docs

---
 lib/stdlib/doc/src/gen_statem.xml | 33 +++++++++++++++------------------
 1 file changed, 15 insertions(+), 18 deletions(-)

(limited to 'lib/stdlib/doc')

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
-- 
cgit v1.2.3