From 447f3cf2d041670d93683de4fab02338b26fbaf1 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 3 Mar 2016 11:27:02 +0100
Subject: Rename state_timeout -> event_timeout

---
 lib/stdlib/doc/src/gen_statem.xml | 36 +++++++++++++++++++++++-------------
 lib/stdlib/src/gen_statem.erl     | 10 +++++-----
 2 files changed, 28 insertions(+), 18 deletions(-)

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index db6a4e03ea..4489ddfb91 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -155,7 +155,7 @@ erlang:'!'            -----> Module:StateName/3
     <p>
       Inserting an event replaces the trick of calling your own
       state handling functions that you often would have to
-      resort to in e.g <seealso marker="gen_fsm">gen_fsm</seealso>
+      resort to in for example <seealso marker="gen_fsm">gen_fsm</seealso>
       to force processing an inserted event before others.
       If you for example in <c>gen_statem</c> postpone an event
       in one state and then call some other state function of yours,
@@ -529,17 +529,16 @@ ok
 	    all other events.
 	  </item>
 	  <item>
-	    If a
-            <seealso marker="#type-state_timeout">
-	      <em><c>state_timeout()</c></em>
+	    If an
+            <seealso marker="#type-event_timeout">
+	      <em><c>event_timeout()</c></em>
 	    </seealso>
 	    is set through
             <seealso marker="#type-action">
 	      <c>action() timeout</c>
 	    </seealso>
-	    a state timer may be started or a timeout zero event
-	    may be enqueued as the newest incoming, that is the last
-	    to process before going into <c>receive</c> for new events.
+	    an event timer may be started or a timeout zero event
+	    may be enqueued.
 	  </item>
 	  <item>
 	    The (possibly new)
@@ -588,7 +587,7 @@ ok
       </desc>
     </datatype>
     <datatype>
-      <name name="state_timeout" />
+      <name name="event_timeout" />
       <desc>
 	<p>
 	  Generate an event of
@@ -600,7 +599,8 @@ ok
 	  If the value is <c>infinity</c> no timer is started.
 	  If it is <c>0</c> the timeout event
 	  is immediately enqueued as the newest received
-	  (unless there are retried or inserted events to process).
+	  (unless there are retried or inserted events to process
+	  since then the timeout is cancelled).
 	  Also note that it is not possible nor needed
 	  to cancel this timeout since it is cancelled automatically
 	  by any other event.
@@ -653,15 +653,25 @@ ok
 	    </seealso>
 	    for this state transition.
 	  </item>
+	  <tag><c>Timeout</c></tag>
+	  <item>
+	    Short for <c>{timeout,Timeout}</c> that is
+	    the timeout message is the timeout time.
+	    This form exists to make the
+	    <seealso marker="#state_function">state function</seealso>
+	    return value <c>{next_state,NextState,NewData,Timeout}</c>
+	    allowed like for
+	    <seealso marker="gen_fsm#Module:StateName/2">
+	      gen_fsm Module:StateName/2</seealso>.
+	  </item>
 	  <tag><c>timeout</c></tag>
 	  <item>
 	    Set the
 	    <seealso marker="#type-transition_option">
-	      <c>transition_option() state_timeout()</c>
+	      <c>transition_option() event_timeout()</c>
 	    </seealso>
 	    to <c><anno>Time</anno></c> with the
-	    <c>EventContent</c> as <c><anno>Msg</anno></c>
-	    for the next state.
+	    <c>EventContent</c> as <c><anno>Msg</anno></c>.
 	  </item>
 	  <tag><c>reply_action()</c></tag>
 	  <item>Reply to a caller.</item>
@@ -1419,7 +1429,7 @@ ok
         <p>
 	  This function is called by a <c>gen_statem</c> when it should
           update its internal state during a release upgrade/downgrade,
-          i.e. when the instruction <c>{update,Module,Change,...}</c>
+          that is when the instruction <c>{update,Module,Change,...}</c>
           where <c>Change={advanced,Extra}</c> is given in
           the <c>appup</c> file. See
           <seealso marker="doc/design_principles:release_handling#instr">
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 438c366f8e..92e26bd7ed 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -77,7 +77,7 @@
 -type callback_mode() :: 'state_functions' | 'handle_event_function'.
 
 -type transition_option() ::
-	postpone() | hibernate() | state_timeout().
+	postpone() | hibernate() | event_timeout().
 -type postpone() ::
 	%% If 'true' postpone the current event
 	%% and retry it when the state changes (=/=)
@@ -85,7 +85,7 @@
 -type hibernate() ::
 	%% If 'true' hibernate the server instead of going into receive
 	boolean().
--type state_timeout() ::
+-type event_timeout() ::
 	%% Generate a ('timeout', Msg, ...) event after Time
 	%% unless some other event is delivered
 	Time :: timeout().
@@ -111,9 +111,9 @@
 	'hibernate' | % Set the hibernate option
 	{'hibernate', Hibernate :: hibernate()} |
 	%%
-	(Timeout :: state_timeout()) | % {timeout,Timeout}
-	{'timeout', % Set the timeout option
-	 Time :: state_timeout(), Msg :: term()} |
+	(Timeout :: event_timeout()) | % {timeout,Timeout}
+	{'timeout', % Set the event timeout option
+	 Time :: event_timeout(), Msg :: term()} |
 	%%
 	reply_action() |
 	%%
-- 
cgit v1.2.3