From 3a60545091d3075e23c4a7af8c18b3641bb084e2 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Tue, 9 Aug 2016 08:59:51 +0200
Subject: Doc fixes

---
 lib/stdlib/doc/src/gen_statem.xml | 56 ++++++++++++++-------------------------
 1 file changed, 20 insertions(+), 36 deletions(-)

(limited to 'lib/stdlib/doc/src/gen_statem.xml')

diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml
index f18c1087ab..3322571b2c 100644
--- a/lib/stdlib/doc/src/gen_statem.xml
+++ b/lib/stdlib/doc/src/gen_statem.xml
@@ -119,9 +119,11 @@ erlang:'!'            -----> Module:StateName/3
     </p>
     <p>
       If a callback function fails or returns a bad value,
-      the <c>gen_statem</c> terminates. However, an exception of class
+      the <c>gen_statem</c> terminates, unless otherwise stated.
+      However, an exception of class
       <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
-      is not regarded as an error but as a valid return.
+      is not regarded as an error but as a valid return
+      from all callback functions.
     </p>
     <marker id="state_function"/>
     <p>
@@ -917,7 +919,8 @@ handle_event(_, _, State, Data) ->
 	</p>
 	<note>
 	  <p>
-	    To avoid getting a late reply in the caller's
+	    For <c><anno>Timeout</anno> =/= infinity</c>,
+	    to avoid getting a late reply in the caller's
 	    inbox, this function spawns a proxy process that
 	    does the call. A late reply gets delivered to the
 	    dead proxy process, hence gets discarded. This is
@@ -1288,12 +1291,6 @@ handle_event(_, _, State, Data) ->
 	  <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso>
 	  returns.
 	</p>
-	<p>
-	  This function can use
-	  <seealso marker="erts:erlang#throw/1"><c>erlang:throw/1</c></seealso>
-	  to return <c>CallbackMode</c>, just for symmetry reasons.
-	  There should be no actual reason to use this.
-	</p>
 	<note>
 	  <p>
 	    If this function's body does not consist of solely one of two
@@ -1368,11 +1365,6 @@ handle_event(_, _, State, Data) ->
 	  It is recommended to use an atom as <c>Reason</c> since
 	  it will be wrapped in an <c>{error,Reason}</c> tuple.
 	</p>
-	<p>
-	  This function can use
-	  <seealso marker="erts:erlang#throw/1"><c>erlang:throw/1</c></seealso>
-	  to return <c>Result</c> or <c>Reason</c>.
-	</p>
       </desc>
     </func>
 
@@ -1432,11 +1424,6 @@ handle_event(_, _, State, Data) ->
 	  or <c>ignore</c>; see
           <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>.
 	</p>
-	<p>
-	  This function can use
-	  <seealso marker="erts:erlang#throw/1"><c>erlang:throw/1</c></seealso>
-	  to return <c>Result</c>.
-	</p>
         <note>
 	  <p>
 	    This callback is optional, so a callback module does not need
@@ -1477,10 +1464,14 @@ handle_event(_, _, State, Data) ->
 	    This callback is optional, so a callback module does not need
 	    to export it. The <c>gen_statem</c> module provides a default
 	    implementation of this function that returns
-	    <c>{State,Data}</c>. If this callback fails, the default
-	    function returns <c>{State,Info}</c>,
-	    where <c>Info</c> informs of the crash but no details,
-	    to hide possibly sensitive data.
+	    <c>{State,Data}</c>.
+	  </p>
+	  <p>
+	    If this callback is exported but fails,
+	    to hide possibly sensitive data,
+	    the default function will instead return <c>{State,Info}</c>,
+	    where <c>Info</c> says nothing but the fact that
+	    <c>format_status/2</c> has crashed.
 	  </p>
         </note>
         <p>This function is called by a <c>gen_statem</c> process when
@@ -1541,11 +1532,6 @@ handle_event(_, _, State, Data) ->
           printed in log files. Another use is to hide sensitive data from
 	  being written to the error log.
 	</p>
-	<p>
-	  This function can use
-	  <seealso marker="erts:erlang#throw/1"><c>erlang:throw/1</c></seealso>
-	  to return <c>Status</c>.
-	</p>
       </desc>
     </func>
 
@@ -1620,9 +1606,12 @@ handle_event(_, _, State, Data) ->
 	  see <seealso marker="#type-action"><c>action()</c></seealso>.
 	</p>
 	<p>
-	  These functions can use
-	  <seealso marker="erts:erlang#throw/1"><c>erlang:throw/1</c></seealso>,
-	  to return the result.
+	  Note the fact that you can use
+	  <seealso marker="erts:erlang#throw/1"><c>throw</c></seealso>
+	  to return the result, which can be useful.
+	  For example to bail out with <c>throw(keep_state_and_data)</c>
+	  from deep within complex code that is in no position to
+	  return <c>{next_state,State,Data}</c>.
 	</p>
       </desc>
     </func>
@@ -1695,11 +1684,6 @@ handle_event(_, _, State, Data) ->
 	  and an error report is issued using
           <seealso marker="kernel:error_logger#format/2"><c>error_logger:format/2</c></seealso>.
 	</p>
-	<p>
-	  This function can use
-	  <seealso marker="erts:erlang#throw/1"><c>erlang:throw/1</c></seealso>
-	  to return <c>Ignored</c>, which is ignored anyway.
-	</p>
       </desc>
     </func>
   </funcs>
-- 
cgit v1.2.3