Update documentation after review

1 files changed, 49 insertions, 18 deletions

diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index b2d769d3a9..d5e8b41c6c 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -108,7 +108,9 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
       <item>
 	Co-located callback code for each state,
 	for all
-	<seealso marker="#Event Types"><em>Event Types</em></seealso>
+	<seealso marker="#Event Types and Event Content">
+	  <em>Event Types</em>
+	</seealso>
 	(such as <em>call</em>, <em>cast</em> and <em>info</em>)
       </item>
       <item>
@@ -136,7 +138,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
 	(<seealso marker="#State Time-Outs">State Time-Outs</seealso>,
 	<seealso marker="#Event Time-Outs">Event Time-Outs</seealso>
 	and
-	<seealso marker="#Generic Time-Outs">Generic Time-outs</seealso>
+	<seealso marker="#Generic Time-Outs">Generic Time-Outs</seealso>
 	(named time-outs))
       </item>
     </list>
@@ -353,9 +355,10 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
     </taglist>
     <p>
       The state is either the name of the function itself or an argument to it.
-      The other arguments are the <c>EventType</c> described in section
-      <seealso marker="#Event Types">Event Types</seealso>,
-      the event dependent <c>EventContent</c>,
+      The other arguments are the <c>EventType</c>
+      and the event dependent <c>EventContent</c>,
+      both described in section
+      <seealso marker="#Event Types and Event Content">Event Types and Event Content</seealso>,
       and the current server <c>Data</c>.
     </p>
     <p>
@@ -638,19 +641,30 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
       and set a time-out to use absolute instead of relative time
       (using the <c>Opts</c> field).
     </p>
+    <p>
+      The different
+      <seealso marker="#Time-Outs">Time-Outs</seealso> and
+      <seealso marker="#Inserted Events"><c>next_event</c></seealso>
+      actions generate new events with corresponding
+      <seealso marker="#Event Types and Event Content">
+	Event Types and Event Content
+      </seealso>.
+    </p>
   </section>
 
 <!-- =================================================================== -->
 
   <section>
-    <marker id="Event Types" />
-    <title>Event Types</title>
+    <marker id="Event Types and Event Content" />
+    <title>Event Types and Event Content</title>
     <p>
       Events are categorized in different
       <seealso marker="stdlib:gen_statem#type-event_type"><em>event types</em></seealso>.
       Events of all types are for a given state
       handled in the same callback function, and that function gets
       <c>EventType</c> and <c>EventContent</c> as arguments.
+      The meaning of the <c>EventContent</c>
+      depends on the <c>EventType</c>.
     </p>
     <p>
       The following is a complete list of <em>event types</em> and where
@@ -664,7 +678,10 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
       </tag>
       <item>
 	Generated by
-	<seealso marker="stdlib:gen_statem#cast/2"><c>gen_statem:cast</c></seealso>.
+	<seealso marker="stdlib:gen_statem#cast/2">
+	  <c>gen_statem:cast(ServerRef, Msg)</c>
+	</seealso>
+	where <c>Msg</c> becomes the <c>EventContent</c>.
       </item>
       <tag>
 	<seealso marker="stdlib:gen_statem#type-external_event_type">
@@ -673,11 +690,17 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
       </tag>
       <item>
 	Generated by
-	<seealso marker="stdlib:gen_statem#call/2"><c>gen_statem:call</c></seealso>,
-	where <c>From</c> is the reply address to use
+	<seealso marker="stdlib:gen_statem#call/2">
+	  <c>gen_statem:call(ServerRef, Request)</c>
+	</seealso>
+	where <c>Request</c> becomes the <c>EventContent</c>.
+	<c>From</c> is the reply address to use
 	when replying either through the <em>transition action</em>
-	<c>{reply,From,Msg}</c> or by calling
-	<seealso marker="stdlib:gen_statem#reply/1"><c>gen_statem:reply</c></seealso>.
+	<c>{reply,From,Reply}</c> or by calling
+	<seealso marker="stdlib:gen_statem#reply/1">
+	  <c>gen_statem:reply(From, Reply)</c>
+	</seealso>
+	from the <em>callback module</em>.
       </item>
       <tag>
 	<seealso marker="stdlib:gen_statem#type-external_event_type">
@@ -687,6 +710,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
       <item>
 	Generated by any regular process message sent to
 	the <c>gen_statem</c> process.
+	The process message becomes the <c>EventContent</c>.
       </item>
       <tag>
 	<seealso marker="stdlib:gen_statem#type-timeout_event_type">
@@ -738,7 +762,7 @@ State(S) x Event(E) -> Actions(A), State(S')</pre>
       </tag>
       <item>
 	Generated by <em>transition action</em>
-	<seealso marker="stdlib:gen_statem#type-enter_action"><c>{next_event,internal,EventContent}</c></seealso>.
+	<seealso marker="stdlib:gen_statem#type-action"><c>{next_event,internal,EventContent}</c></seealso>.
 	All <em>event types</em> above can also be generated using
 	the <c>next_event</c> action:
 	<c>{next_event,EventType,EventContent}</c>.
@@ -807,7 +831,7 @@ StateName(EventType, EventContent, Data) ->
 
   <section>
     <marker id="Time-Outs" />
-    <title>Time-outs</title>
+    <title>Time-Outs</title>
     <p>
       Time-outs in <c>gen_statem</c> are started from a
       <seealso marker="#Transition Actions">
@@ -884,8 +908,11 @@ StateName(EventType, EventContent, Data) ->
 	so why not set it to <c>undefined</c>.
       </p>
       <p>
-	A more explicit way to cancel a timer is to use
-	a <em>transition action</em> on the form
+	A more explicit way to cancel a timer is to use a
+	<seealso marker="#Transition Actions">
+	  <em>transition action</em>
+	</seealso>
+	on the form
 	<seealso marker="stdlib:gen_statem#type-timeout_cancel_action">
 	  <c>{TimeoutType, cancel}</c>
 	</seealso>
@@ -897,7 +924,11 @@ StateName(EventType, EventContent, Data) ->
       <title>Updating a Time-Out</title>
       <p>
 	While a time-out is running, its <c>EventContent</c>
-	can be updated using a <em>transition action</em> on the form
+	can be updated using a
+	<seealso marker="#Transition Actions">
+	  <em>transition action</em>
+	</seealso>
+	on the form
 	<seealso marker="stdlib:gen_statem#type-timeout_update_action">
 	  <c>{TimeoutType, update, NewEventContent}</c>
 	</seealso>
@@ -1907,7 +1938,7 @@ open(state_timeout, lock, Data) ->
       <seealso marker="#Transition Actions">
 	<em>transition action</em>
       </seealso>
-      <c>{next_event,EventType,EventContent}</c>.
+      <seealso marker="stdlib:gen_statem#type-action"><c>{next_event,EventType,EventContent}</c></seealso>.
     </p>
     <p>
       You can generate events of any existing