Document system_events better

3 files changed, 184 insertions, 2 deletions

diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml
index 9fe816e33a..78ae4b5c38 100644
--- a/lib/stdlib/doc/src/sys.xml
+++ b/lib/stdlib/doc/src/sys.xml
@@ -114,6 +114,154 @@
     </datatype>
     <datatype>
       <name name="system_event"/>
+      <desc>
+	<taglist>
+	  <tag><c>{in,<anno>Msg</anno>}</c></tag>
+	  <item>
+	    <p>
+	      Is produced by <c>gen_server</c> and <c>gen_event</c>
+	      when the message <c>Msg</c> arrives.
+	    </p>
+	  </item>
+	  <tag><c>{in,<anno>Msg</anno>,<anno>State</anno>}</c></tag>
+	  <item>
+	    <p>
+	      Is produced by <c>gen_statem</c>
+	      when the message <c>Msg</c> arrives in state <c>State</c>.
+	    </p>
+	    <p>
+	      For <c>gen_statem</c> the <c><anno>Msg</anno></c> term is
+	      an <c>{EventType,EventContent}</c> tuple.
+	    </p>
+	  </item>
+	  <tag><c>{out,<anno>Msg</anno>,<anno>To</anno>}</c></tag>
+	  <item>
+	    <p>
+	      Is produced by <c>gen_statem</c> when the reply <c>Msg</c>
+	      is sent back to <c>To</c> by returning
+	      a <c>{reply,To,Msg}</c> action from the callback module.
+	    </p>
+	    <p>
+	      <c><anno>To</anno></c> is of the same type
+	      as the first argument to <c>gen_statem:reply/2</c>.
+	    </p>
+	  </item>
+	  <tag>
+	    <c>{out,<anno>Msg</anno>,<anno>To</anno>,<anno>State</anno>}</c>
+	  </tag>
+	  <item>
+	    <p>
+	      Is produced by <c>gen_server</c>
+	      when the reply <c><anno>Msg</anno></c>
+	      is sent back to <c><anno>To</anno></c>
+	      by returning a <c>{reply,...}</c> tuple
+	      from the callback module.
+	    </p>
+	    <p>
+	      <c><anno>To</anno></c> is of the same type
+	      as the first argument to <c>gen_server:reply/2</c>.
+	    </p>
+	    <p>
+	      <c><anno>State</anno></c> is the new server state.
+	    </p>
+	  </item>
+	  <tag>
+	    <c>{noreply,<anno>State</anno>}</c>
+	  </tag>
+	  <item>
+	    <p>
+	      Is produced by <c>gen_server</c>
+	      when a <c>{noreply,...}</c> tuple is returned
+	      from the callback module.
+	    </p>
+	    <p>
+	      <c><anno>State</anno></c> is the new server state.
+	    </p>
+	  </item>
+	  <tag>
+	    <c>{continue,<anno>Continuation</anno>}</c>
+	  </tag>
+	  <item>
+	    <p>
+	      Is produced by <c>gen_server</c>
+	      when a <c>{continue,<anno>Continuation</anno>}</c>
+	      tuple is returned from the callback module.
+	    </p>
+	  </item>
+	  <tag>
+	    <c>{code_change,<anno>Event</anno>,<anno>State</anno>}</c>
+	  </tag>
+	  <item>
+	    <p>
+	      Is produced by <c>gen_statem</c>
+	      when the message <c><anno>Event</anno></c>
+	      arrives in state <c><anno>State</anno></c>
+	      as the first event after a code change.
+	    </p>
+	    <p>
+	      <c><anno>Event</anno></c> is
+	      an <c>{EventType,EventContent}</c> tuple.
+	    </p>
+	  </item>
+	  <tag>
+	    <c>
+	      {postpone,<anno>Event</anno>,<anno>State</anno>,<anno>NextState</anno>}
+	    </c>
+	  </tag>
+	  <item>
+	    <p>
+	      Is produced by <c>gen_statem</c>
+	      when the message <c><anno>Event</anno></c>
+	      is postponed in state <c><anno>State</anno></c>.
+	      <c><anno>NextState</anno></c> is the new state.
+	    </p>
+	    <p>
+	      <c><anno>Event</anno></c> is
+	      an <c>{EventType,EventContent}</c> tuple.
+	    </p>
+	  </item>
+	  <tag>
+	    <c>
+	      {consume,<anno>Event</anno>,<anno>State</anno>,<anno>NextState</anno>}
+	    </c>
+	  </tag>
+	  <item>
+	    <p>
+	      Is produced by <c>gen_statem</c>
+	      when the message <c><anno>Event</anno></c>
+	      is consumed in state <c><anno>State</anno></c>.
+	      <c><anno>NextState</anno></c> is the new state.
+	    </p>
+	    <p>
+	      <c><anno>Event</anno></c> is
+	      an <c>{EventType,EventContent}</c> tuple.
+	    </p>
+	  </item>
+	  <tag>
+	    <c>
+	      {enter,<anno>State</anno>}
+	    </c>
+	  </tag>
+	  <item>
+	    <p>
+	      Is produced by <c>gen_statem</c>
+	      when the first state <c><anno>State</anno></c> is entered.
+	    </p>
+	  </item>
+	  <tag>
+	    <c>
+	      {terminate,<anno>Reason</anno>,<anno>State</anno>}
+	    </c>
+	  </tag>
+	  <item>
+	    <p>
+	      Is produced by <c>gen_statem</c>
+	      when it terminates with reason <c><anno>Reason</anno></c>
+	      in state <c><anno>State</anno></c>.
+	    </p>
+	  </item>
+	</taglist>
+      </desc>
     </datatype>
     <datatype>
       <name name="dbg_opt"/>
@@ -532,6 +680,12 @@
       <name name="get_debug" arity="3"/>
       <fsummary>Get the data associated with a debug option.</fsummary>
       <desc>
+	<warning>
+	  <p>
+	    <c>get_debug/3</c> is deprecated since it returns
+	    data of an internal type only useful for debugging.
+	  </p>
+	</warning>
         <p>Gets the data associated with a debug option.
           <c><anno>Default</anno></c>
           is returned if <c><anno>Item</anno></c> is not found. Can be
@@ -605,6 +759,18 @@
     </func>
 
     <func>
+      <name name="get_log" arity="1"/>
+      <fsummary>Return the logged events in the debug structure.</fsummary>
+      <desc>
+        <p>
+	  Returns the logged system events in the debug structure,
+	  that is the last argument to
+          <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>.
+	</p>
+      </desc>
+    </func>
+
+    <func>
       <name>Module:system_code_change(Misc, Module, OldVsn, Extra) ->
         {ok, NMisc}</name>
       <fsummary>Called when the process is to perform a code change.</fsummary>
diff --git a/lib/stdlib/src/otp_internal.erl b/lib/stdlib/src/otp_internal.erl
index aaed13ba3a..a0fbd259e2 100644
--- a/lib/stdlib/src/otp_internal.erl
+++ b/lib/stdlib/src/otp_internal.erl
@@ -55,6 +55,14 @@ obsolete_1(erlang, now, 0) ->
 obsolete_1(calendar, local_time_to_universal_time, 1) ->
     {deprecated, {calendar, local_time_to_universal_time_dst, 1}};
 
+%% *** STDLIB added in OTP 22 ***
+
+obsolete_1(sys, get_debug, 3) ->
+    {deprecated,
+     "Deprecated function. "
+     "Incorrectly documented and in fact only for internal use. "
+     "Can often be replaced with sys:get_log/1."};
+
 %% *** STDLIB added in OTP 20 ***
 
 obsolete_1(gen_fsm, start, 3) ->
diff --git a/lib/stdlib/src/sys.erl b/lib/stdlib/src/sys.erl
index 09fe497d11..11513b3482 100644
--- a/lib/stdlib/src/sys.erl
+++ b/lib/stdlib/src/sys.erl
@@ -31,6 +31,7 @@
 	 install/2, install/3, remove/2, remove/3]).
 -export([handle_system_msg/6, handle_system_msg/7, handle_debug/4,
 	 print_log/1, get_log/1, get_debug/3, debug_options/1, suspend_loop_hib/6]).
+-deprecated([{get_debug,3,eventually}]).
 
 %%-----------------------------------------------------------------
 %% Types
@@ -42,10 +43,17 @@
                       | {'global', term()}
                       | {'via', module(), term()}.
 -type system_event() :: {'in', Msg :: _}
-                      | {'in', Msg :: _, From :: _}
+                      | {'in', Msg :: _, State :: _}
                       | {'out', Msg :: _, To :: _}
                       | {'out', Msg :: _, To :: _, State :: _}
-                        | term().
+                      | {'noreply', State :: _}
+                      | {'continue', Continuation :: _}
+                      | {'code_change', Event :: _, State :: _}
+                      | {'postpone', Event :: _, State :: _, NextState :: _}
+                      | {'consume', Event :: _, State :: _, NextState :: _}
+                      | {'enter', State :: _}
+                      | {'terminate', Reason :: _, State :: _}
+                      | term().
 -opaque dbg_opt()    :: {'trace', 'true'}
                       | {'log',
                          {N :: non_neg_integer(),