From 800265f49f912dcf66846b13aa8032bf2f380caf Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Fri, 30 Sep 2016 11:17:22 +0200
Subject: Improve docs and types

---
 lib/stdlib/doc/src/gen_statem.xml | 77 +++++++++++++++++++++++++++++++--------
 lib/stdlib/src/gen_statem.erl     | 38 +++++++++++++------
 2 files changed, 88 insertions(+), 27 deletions(-)

(limited to 'lib')

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