From a447b904cff36fa2d690f1d0068eb28589369787 Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Mon, 5 Nov 2018 16:40:52 +0100
Subject: Document system_events better

---
 lib/stdlib/doc/src/sys.xml | 166 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)

(limited to 'lib/stdlib/doc')

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
@@ -604,6 +758,18 @@
       </desc>
     </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>
-- 
cgit v1.2.3