Improve docs and types

3 files changed, 101 insertions, 31 deletions

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index aa34f53d29..bba2de5e77 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -674,6 +674,9 @@ handle_event(_, _, State, Data) ->
 	      they are merged with the current
 	      That is: <c>hibernate</c> and <c>timeout</c> overrides
 	      the current and <c>reply</c> sends a reply.
+	      This has the same effect as if you would have appended
+	      the actions from this state enter call to the actions
+	      returned by the state function that changed states.
             </p>
 	  </item>
 	  <item>
@@ -1002,28 +1005,42 @@ handle_event(_, _, State, Data) ->
       </desc>
     </datatype>
     <datatype>
-      <name name="common_state_callback_result"/>
+      <name name="keep_state_callback_result"/>
       <desc>
 	<taglist>
-	  <tag><c>stop</c></tag>
+	  <tag><c>keep_state</c></tag>
 	  <item>
 	    <p>
-	      Terminates the <c>gen_statem</c> by calling
-	      <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso>
-	      with <c>Reason</c> and
-	      <c><anno>NewData</anno></c>, if specified.
+	      The <c>gen_statem</c> keeps the current state, or
+	      does a state transition to the current state if you like,
+	      sets <c><anno>NewData</anno></c>,
+	      and executes all <c><anno>Actions</anno></c>.
+	      This is the same as
+	      <c>{next_state,CurrentState,<anno>NewData</anno>,<anno>Actions</anno>}</c>.
 	    </p>
 	  </item>
-	  <tag><c>stop_and_reply</c></tag>
+	  <tag><c>keep_state_and_data</c></tag>
 	  <item>
 	    <p>
-	      Sends all <c><anno>Replies</anno></c>,
-	      then terminates the <c>gen_statem</c> by calling
-	      <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso>
-	      with <c>Reason</c> and
-	      <c><anno>NewData</anno></c>, if specified.
+	      The <c>gen_statem</c> keeps the current state or
+	      does a state transition to the current state if you like,
+	      keeps the current server data,
+	      and executes all <c><anno>Actions</anno></c>.
+	      This is the same as
+	      <c>{next_state,CurrentState,CurrentData,<anno>Actions</anno>}</c>.
 	    </p>
 	  </item>
+	</taglist>
+	<p>
+	  All these terms are tuples or atoms and this property
+	  will hold in any future version of <c>gen_statem</c>.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="keep_state_callback_enter_result"/>
+      <desc>
+	<taglist>
 	  <tag><c>keep_state</c></tag>
 	  <item>
 	    <p>
@@ -1053,6 +1070,36 @@ handle_event(_, _, State, Data) ->
 	</p>
       </desc>
     </datatype>
+    <datatype>
+      <name name="common_state_callback_result"/>
+      <desc>
+	<taglist>
+	  <tag><c>stop</c></tag>
+	  <item>
+	    <p>
+	      Terminates the <c>gen_statem</c> by calling
+	      <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso>
+	      with <c>Reason</c> and
+	      <c><anno>NewData</anno></c>, if specified.
+	    </p>
+	  </item>
+	  <tag><c>stop_and_reply</c></tag>
+	  <item>
+	    <p>
+	      Sends all <c><anno>Replies</anno></c>,
+	      then terminates the <c>gen_statem</c> by calling
+	      <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso>
+	      with <c>Reason</c> and
+	      <c><anno>NewData</anno></c>, if specified.
+	    </p>
+	  </item>
+	</taglist>
+	<p>
+	  All these terms are tuples or atoms and this property
+	  will hold in any future version of <c>gen_statem</c>.
+	</p>
+      </desc>
+    </datatype>
   </datatypes>
 
   <funcs>
@@ -1462,7 +1509,7 @@ handle_event(_, _, State, Data) ->
 	  CallbackMode =
 	  <seealso marker="#type-callback_mode">callback_mode()</seealso> |
 	  [ <seealso marker="#type-callback_mode">callback_mode()</seealso>
-	  | <seealso marker="#type-state_entry_mode"><c>state_entry_events</c></seealso> ]
+	  | <seealso marker="#type-state_enter">state_enter()</seealso> ]
 	</v>
       </type>
       <desc>
@@ -1490,9 +1537,9 @@ handle_event(_, _, State, Data) ->
 	</p>
 	<p>
 	  The <c>CallbackMode</c> is either just
-	  <seealso marker="#type-callback_mode">callback_mode()</seealso>
+	  <seealso marker="#type-callback_mode"><c>callback_mode()</c></seealso>
 	  or a list containing
-	  <seealso marker="#type-callback_mode">callback_mode()</seealso>
+	  <seealso marker="#type-callback_mode"><c>callback_mode()</c></seealso>
 	  and possibly the atom
 	  <seealso marker="#type-state_enter"><c>state_enter</c></seealso>.
 	</p>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index aedcfc932f..9f5573af86 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -142,7 +142,7 @@
 	 NextStateName :: state_name(),
 	 NewData :: data(),
 	 Actions :: [action()] | action()} |
-	common_state_callback_result().
+	keep_state_callback_result().
 -type state_function_enter_result() ::
 	{'next_state', % {next_state,NextStateName,NewData,[]}
 	 NextStateName :: state_name(),
@@ -151,7 +151,7 @@
 	 NextStateName :: state_name(),
 	 NewData :: data(),
 	 Actions :: [enter_action()] | enter_action()} |
-	common_state_callback_result().
+	keep_state_callback_enter_result().
 
 -type handle_event_result() ::
 	{'next_state', % {next_state,NextState,NewData,[]}
@@ -161,7 +161,7 @@
 	 NextState :: state(),
 	 NewData :: data(),
 	 Actions :: [action()] | action()} |
-	common_state_callback_result().
+	keep_state_callback_result().
 -type handle_event_enter_result() ::
 	{'next_state', % {next_state,NextState,NewData,[]}
 	 NextState :: state(),
@@ -170,6 +170,28 @@
 	 NextState :: state(),
 	 NewData :: data(),
 	 Actions :: [enter_action()] | enter_action()} |
+	keep_state_callback_enter_result().
+
+-type keep_state_callback_result() ::
+	{'keep_state', % {keep_state,NewData,[]}
+	 NewData :: data()} |
+	{'keep_state', % Keep state, change data
+	 NewData :: data(),
+	 Actions :: [action()] | action()} |
+	'keep_state_and_data' | % {keep_state_and_data,[]}
+	{'keep_state_and_data', % Keep state and data -> only actions
+	 Actions :: [action()] | action()} |
+	common_state_callback_result().
+
+-type keep_state_callback_enter_result() ::
+	{'keep_state', % {keep_state,NewData,[]}
+	 NewData :: data()} |
+	{'keep_state', % Keep state, change data
+	 NewData :: data(),
+	 Actions :: [enter_action()] | enter_action()} |
+	'keep_state_and_data' | % {keep_state_and_data,[]}
+	{'keep_state_and_data', % Keep state and data -> only actions
+	 Actions :: [enter_action()] | enter_action()} |
 	common_state_callback_result().
 
 -type common_state_callback_result() ::
@@ -185,15 +207,7 @@
 	{'stop_and_reply', % Reply then stop the server
 	 Reason :: term(),
 	 Replies :: [reply_action()] | reply_action(),
-	 NewData :: data()} |
-	{'keep_state', % {keep_state,NewData,[]}
-	 NewData :: data()} |
-	{'keep_state', % Keep state, change data
-	 NewData :: data(),
-	 Actions :: [ActionType] | ActionType} |
-	'keep_state_and_data' | % {keep_state_and_data,[]}
-	{'keep_state_and_data', % Keep state and data -> only actions
-	 Actions :: [ActionType] | ActionType}.
+	 NewData :: data()}.
 
 
 %% The state machine init function.  It is called only once and
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index d2a9b23570..69d1e8e9fa 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -29,7 +29,7 @@
     <rev></rev>
     <file>statem.xml</file>
   </header>
-  <marker id="gen_statem behaviour"></marker>
+  <marker id="gen_statem Behaviour"></marker>
   <p>
     This section is to be read with the
     <seealso marker="stdlib:gen_statem"><c>gen_statem(3)</c></seealso>
@@ -199,7 +199,10 @@ handle_event(EventType, EventContent, State, Data) ->
     <title>State Enter Calls</title>
     <p>
       The <c>gen_statem</c> behavior can regardless of callback mode
-      automatically call the state function
+      automatically
+      <seealso marker="stdlib:gen_statem#type-state_enter">
+	call the state function
+      </seealso>
       with special arguments whenever the state changes
       so you can write state entry actions
       near the rest of the state transition rules.
@@ -214,8 +217,13 @@ StateName(EventType, EventContent, Data) ->
     {next_state, NewStateName, NewData}.</pre>
     <p>
       Depending on how your state machine is specified,
-      this can be a very useful feature, but if you use it
-      you will have to handle the state enter call in all states.
+      this can be a very useful feature,
+      but it forces you to handle the state enter calls in all states.
+      See also the
+      <seealso marker="#State Entry Actions">
+	State Entry Actions
+      </seealso>
+      chapter.
     </p>
   </section>
 
@@ -964,6 +972,7 @@ do_unlock() ->
 <!-- =================================================================== -->
 
   <section>
+    <marker id="State Entry Actions"></marker>
     <title>State Entry Actions</title>
     <p>
       Say you have a state machine specification