1 files changed, 48 insertions, 8 deletions
diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index 4a824f073e..be0d64feba 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2016</year><year>2017</year>
+      <year>2016</year><year>2018</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -543,7 +543,23 @@ handle_event(_, _, State, Data) ->
       <name name="event_type"/>
       <desc>
 	<p>
-	  External events are of three types:
+	  There are 3 categories of events:
+	  <seealso marker="#type-external_event_type">external</seealso>,
+	  <seealso marker="#type-timeout_event_type">timeout</seealso>,
+	  and <c>internal</c>.
+	</p>
+	<p>
+	  <c>internal</c> events can only be generated by the
+	  state machine itself through the state transition action
+	  <seealso marker="#type-action"><c>next_event</c></seealso>.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="external_event_type"/>
+      <desc>
+	<p>
+	  External events are of 3 types:
 	  <c>{call,<anno>From</anno>}</c>, <c>cast</c>, or <c>info</c>.
 	  <seealso marker="#call/2">Calls</seealso>
 	  (synchronous) and
@@ -551,12 +567,17 @@ handle_event(_, _, State, Data) ->
 	  originate from the corresponding API functions.
 	  For calls, the event contains whom to reply to.
 	  Type <c>info</c> originates from regular process messages sent
-	  to the <c>gen_statem</c>. The state machine
-	  implementation can, in addition to the above,
-	  generate
-	  <seealso marker="#type-event_type"><c>events of types</c></seealso>
-	  <c>timeout</c>, <c>{timeout,<anno>Name</anno>}</c>,
-	  <c>state_timeout</c>, and <c>internal</c> to itself.
+	  to the <c>gen_statem</c>.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="timeout_event_type"/>
+      <desc>
+	<p>
+	  There are 3 types of timeout events that the state machine
+	  can generate for itself with the corresponding
+	  <seealso marker="#type-timeout_action">timeout_action()</seealso>s.
 	</p>
       </desc>
     </datatype>
@@ -1026,6 +1047,25 @@ handle_event(_, _, State, Data) ->
 	      for this state transition.
 	    </p>
 	  </item>
+	</taglist>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="timeout_action"/>
+      <desc>
+	<p>
+	  These state transition actions can be invoked by
+	  returning them from the
+	  <seealso marker="#state callback">state callback</seealso>, from
+	  <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
+	  or by giving them to
+	  <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>.
+	</p>
+	<p>
+	  These timeout actions sets timeout
+	  <seealso marker="#type-transition_option">transition options</seealso>.
+	</p>
+	<taglist>
 	  <tag><c>Timeout</c></tag>
 	  <item>
 	    <p>