Merge branch 'raimo/new-gen-state-machine/OTP-13065'

* raimo/new-gen-state-machine/OTP-13065: (52 commits)
  Add section on state filtering
  Promote gen_statem over gen_fsm
  Modify code_change/4 to return CallbackMode
  Use ?NAME macro in examples
  Introduce Fred Herbert suggested additions
  Introduce corrections from Fred Hebert and Ingela
  Use .png pictures instead of .gif
  Write Design Principles chapter
  Fix missing short forms for event timeout
  Do more intricate Fred Hebert doc changes
  Change Caller -> From as suggested by Fred Hebert
  Do documentation improvements from Fred Hebert
  Fix broken documenation reference
  Rename state_timeout -> event_timeout
  Fix most of the system docs and emacs mode
  Change code_change/4 to {ok,State,Data}
  Fixup sharpened test suite
  Sharpen test suite
  Remove the remove_event action and all alike
  Relax caller() type check and cleanup
  ...

Conflicts:
	lib/stdlib/src/gen.erl
	lib/stdlib/src/gen_event.erl
	lib/stdlib/src/gen_fsm.erl
	lib/stdlib/src/gen_server.erl
	lib/stdlib/test/error_logger_forwarder.erl

1 files changed, 20 insertions, 9 deletions

diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml
index d80ec4dfa6..2255395f46 100644
--- a/lib/stdlib/doc/src/sys.xml
+++ b/lib/stdlib/doc/src/sys.xml
@@ -217,14 +217,18 @@
           processes. For example, a <c>gen_server</c> process returns
           the callback module's state, a <c>gen_fsm</c> process
           returns information such as its current state name and state data,
-          and a <c>gen_event</c> process returns information about each of its
+	  a <c>gen_statem</c> process returns information about
+	  its current state and data, and a <c>gen_event</c> process
+	  returns information about each of its
           registered handlers. Callback modules for <c>gen_server</c>,
-          <c>gen_fsm</c>, and <c>gen_event</c> can also customise the value
+          <c>gen_fsm</c>, <c>gen_statem</c> and <c>gen_event</c>
+	  can also customise the value
           of <c><anno>Misc</anno></c> by exporting a <c>format_status/2</c>
           function that contributes module-specific information;
-          see <seealso marker="gen_server#Module:format_status/2">gen_server:format_status/2</seealso>,
-          <seealso marker="gen_fsm#Module:format_status/2">gen_fsm:format_status/2</seealso>, and
-          <seealso marker="gen_event#Module:format_status/2">gen_event:format_status/2</seealso>
+          see <seealso marker="gen_server#Module:format_status/2">gen_server format_status/2</seealso>,
+          <seealso marker="gen_fsm#Module:format_status/2">gen_fsm format_status/2</seealso>,
+          <seealso marker="gen_statem#Module:format_status/2">gen_statem format_status/2</seealso>, and
+          <seealso marker="gen_event#Module:format_status/2">gen_event format_status/2</seealso>
           for more details.</p>
       </desc>
     </func>
@@ -245,6 +249,8 @@
           processes. For a <c>gen_server</c> process, the returned <c><anno>State</anno></c>
           is simply the callback module's state. For a <c>gen_fsm</c> process,
           <c><anno>State</anno></c> is the tuple <c>{CurrentStateName, CurrentStateData}</c>.
+	  For a <c>gen_statem</c> process <c><anno>State</anno></c> is
+	  the tuple <c>{CurrentState,CurrentData}.</c>
           For a <c>gen_event</c> process, <c><anno>State</anno></c> a list of tuples,
           where each tuple corresponds to an event handler registered in the process and contains
           <c>{Module, Id, HandlerState}</c>, where <c>Module</c> is the event handler's module name,
@@ -263,8 +269,9 @@
           details of the exception.</p>
         <p>The <c>system_get_state/1</c> function is primarily useful for user-defined
           behaviours and modules that implement OTP <seealso marker="#special_process">special
-          processes</seealso>. The <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_event</c> OTP
-          behaviour modules export this function, and so callback modules for those behaviours
+          processes</seealso>. The <c>gen_server</c>, <c>gen_fsm</c>,
+	  <c>gen_statem</c> and <c>gen_event</c> OTP
+          behaviour modules export this function, so callback modules for those behaviours
           need not supply their own.</p>
         <p>To obtain more information about a process, including its state, see
           <seealso marker="#get_status-1">get_status/1</seealso> and
@@ -290,6 +297,8 @@
           <c>gen_fsm</c> process, <c><anno>State</anno></c> is the tuple
           <c>{CurrentStateName, CurrentStateData}</c>, and <c><anno>NewState</anno></c>
           is a similar tuple that may contain a new state name, new state data, or both.
+	  The same applies for a <c>gen_statem</c> process but
+	  it names the tuple fields <c>{CurrentState,CurrentData}</c>.
           For a <c>gen_event</c> process, <c><anno>State</anno></c> is the tuple
           <c>{Module, Id, HandlerState}</c> where <c>Module</c> is the event handler's module name,
           <c>Id</c> is the handler's ID (which is the value <c>false</c> if it was registered without
@@ -304,7 +313,8 @@
           state, then regardless of process type, it may simply return its <c><anno>State</anno></c>
           argument.</p>
         <p>If a <c><anno>StateFun</anno></c> function crashes or throws an exception, then
-          for <c>gen_server</c> and <c>gen_fsm</c> processes, the original state of the process is
+          for <c>gen_server</c>, <c>gen_fsm</c> or <c>gen_statem</c> processes,
+	  the original state of the process is
           unchanged. For <c>gen_event</c> processes, a crashing or failing <c><anno>StateFun</anno></c>
           function means that only the state of the particular event handler it was working on when it
           failed or crashed is unchanged; it can still succeed in changing the states of other event
@@ -329,7 +339,8 @@
           <c>{callback_failed, StateFun, {Class, Reason}}</c>.</p>
         <p>The <c>system_replace_state/2</c> function is primarily useful for user-defined behaviours and
           modules that implement OTP <seealso marker="#special_process">special processes</seealso>. The
-          <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_event</c> OTP behaviour modules export this function,
+          <c>gen_server</c>, <c>gen_fsm</c>, <c>gen_statem</c> and
+	  <c>gen_event</c> OTP behaviour modules export this function,
           and so callback modules for those behaviours need not supply their own.</p>
       </desc>
     </func>