Doc fixes

3 files changed, 27 insertions, 42 deletions

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>
diff --git a/lib/stdlib/src/gen_statem.erl b/lib/stdlib/src/gen_statem.erl
index 6d7b461ee3..a39503cb6b 100644
--- a/lib/stdlib/src/gen_statem.erl
+++ b/lib/stdlib/src/gen_statem.erl
@@ -1295,7 +1295,7 @@ format_status(Opt, PDict, #{module := Module}, State, Data) ->
 		_:_ ->
 		    format_status_default(
 		      Opt, State,
-		      "Module:format_status/2 crashed")
+		      atom_to_list(Module) ++ ":format_status/2 crashed")
 	    end;
 	false ->
 	    format_status_default(Opt, State, Data)
@@ -1303,10 +1303,10 @@ format_status(Opt, PDict, #{module := Module}, State, Data) ->
 
 %% The default Module:format_status/2
 format_status_default(Opt, State, Data) ->
-    SSD = {State,Data},
+    StateData = {State,Data},
     case Opt of
 	terminate ->
-	    SSD;
+	    StateData;
 	_ ->
-	    [{data,[{"State",SSD}]}]
+	    [{data,[{"State",StateData}]}]
     end.
diff --git a/system/doc/design_principles/statem.xml b/system/doc/design_principles/statem.xml
index 1351997bc1..f785ca9650 100644
--- a/system/doc/design_principles/statem.xml
+++ b/system/doc/design_principles/statem.xml
@@ -608,7 +608,7 @@ init(Args) ->
 	callback function <c>terminate(shutdown, State, Data)</c>.
       </p>
       <p>
-	In the following example, function <c>terminate/3</c>
+	In this example, function <c>terminate/3</c>
 	locks the door if it is open, so we do not accidentally leave the door
 	open when the supervision tree terminates:
       </p>
@@ -1217,7 +1217,8 @@ format_status(Opt, [_PDict,State,Data]) ->
       <seealso marker="stdlib:gen_statem#Module:format_status/2"><c>Module:format_status/2</c></seealso>
       function. If you do not, a default implementation is used that
       does the same as this example function without filtering
-      the <c>Data</c> term, that is, <c>StateData = {State,Data}</c>.
+      the <c>Data</c> term, that is, <c>StateData = {State,Data}</c>,
+      in this example containing sensitive information.
     </p>
   </section>