r

Use Erlang specs and types for documentation

1 files changed, 77 insertions, 135 deletions

diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml
index efa8922a9d..073faf2df2 100644
--- a/lib/stdlib/doc/src/sys.xml
+++ b/lib/stdlib/doc/src/sys.xml
@@ -39,24 +39,12 @@
     <p>Functions used for implementation of processes 
       should also understand system messages such as debugging
       messages and code change. These functions must be used to implement the use of system messages for a process; either directly, or through standard behaviours, such as <c>gen_server</c>.</p>
-    <p>The following types are used in the functions defined below:</p>
-    <list type="bulleted">
-      <item>
-        <p><c>Name = pid() | atom() | {global, atom()}</c></p>
-      </item>
-      <item>
-        <p><c>Timeout = int() >= 0 | infinity</c></p>
-      </item>
-      <item>
-        <p><c>system_event() = {in, Msg} | {in, Msg, From} | {out, Msg, To} | term()</c></p>
-      </item>
-    </list>
     <p>The default timeout is 5000 ms, unless otherwise specified. The
       <c>timeout</c> defines the time period to wait for the process to
       respond to a request. If the process does not respond, the
       function evaluates <c>exit({timeout, {M, F, A}})</c>.
       </p>
-    <p>The functions make reference to a debug structure.
+    <p><marker id="dbg_opt"/>The functions make reference to a debug structure.
       The debug structure is a list of <c>dbg_opt()</c>.
       <c>dbg_opt()</c> is an internal data type used by the
       <c>handle_system_msg/6</c> function. No debugging is performed if it is an empty list.
@@ -113,20 +101,31 @@
       own system events. It is always up to the process itself
       to format these events.</p>
   </section>
+  <datatypes>
+    <datatype>
+      <name name="name"/>
+    </datatype>
+    <datatype>
+      <name name="system_event"/>
+    </datatype>
+    <datatype>
+      <name name="dbg_opt"/>
+      <desc><p>See <seealso marker="#dbg_opt">above</seealso>.</p></desc>
+    </datatype>
+    <datatype>
+      <name name="dbg_fun"/>
+    </datatype>
+  </datatypes>
   <funcs>
     <func>
-      <name>log(Name,Flag)</name>
-      <name>log(Name,Flag,Timeout) -> ok | {ok, [system_event()]}</name>
+      <name name="log" arity="2"/>
+      <name name="log" arity="3"/>
       <fsummary>Log system events in memory</fsummary>
-      <type>
-        <v>Flag = true | {true, N} | false | get | print</v>
-        <v>N = integer() > 0</v>
-      </type>
       <desc>
         <p>Turns the logging of system events On or Off. If On, a
-          maximum of <c>N</c>  events are kept in the
-          debug structure (the default is 10). If <c>Flag</c> is <c>get</c>, a list of all
-          logged events is returned. If <c>Flag</c> is <c>print</c>, the
+          maximum of <c><anno>N</anno></c>  events are kept in the
+          debug structure (the default is 10). If <c><anno>Flag</anno></c> is <c>get</c>, a list of all
+          logged events is returned. If <c><anno>Flag</anno></c> is <c>print</c>, the
           logged events are printed to <c>standard_io</c>. The events are
           formatted with a function that is defined by the process that
           generated the event (with a call to
@@ -134,13 +133,9 @@
       </desc>
     </func>
     <func>
-      <name>log_to_file(Name,Flag)</name>
-      <name>log_to_file(Name,Flag,Timeout) -> ok | {error, open_file}</name>
+      <name name="log_to_file" arity="2"/>
+      <name name="log_to_file" arity="3"/>
       <fsummary>Log system events to the specified file</fsummary>
-      <type>
-        <v>Flag = FileName | false</v>
-        <v>FileName = string()</v>
-      </type>
       <desc>
         <p>Enables or disables the logging of all system events in textual
           format to the file. The events are formatted with a function that is 
@@ -149,27 +144,18 @@
       </desc>
     </func>
     <func>
-      <name>statistics(Name,Flag)</name>
-      <name>statistics(Name,Flag,Timeout) -> ok | {ok, Statistics} </name>
+      <name name="statistics" arity="2"/>
+      <name name="statistics" arity="3"/>
       <fsummary>Enable or disable the collections of statistics</fsummary>
-      <type>
-        <v>Flag = true | false | get</v>
-        <v>Statistics = [{start_time, {Date1, Time1}}, {current_time, {Date, Time2}}, {reductions, integer()}, {messages_in, integer()}, {messages_out, integer()}]</v>
-        <v>Date1 = Date2 = {Year, Month, Day}</v>
-        <v>Time1 = Time2 = {Hour, Min, Sec}</v>
-      </type>
       <desc>
-        <p>Enables or disables the collection of statistics. If <c>Flag</c> is
+        <p>Enables or disables the collection of statistics. If <c><anno>Flag</anno></c> is
           <c>get</c>, the statistical collection is returned.</p>
       </desc>
     </func>
     <func>
-      <name>trace(Name,Flag)</name>
-      <name>trace(Name,Flag,Timeout) -> void()</name>
+      <name name="trace" arity="2"/>
+      <name name="trace" arity="3"/>
       <fsummary>Print all system events on <c>standard_io</c></fsummary>
-      <type>
-        <v>Flag = boolean()</v>
-      </type>
       <desc>
         <p>Prints all system events on <c>standard_io</c>. The events are
           formatted with a function that is defined by the process that
@@ -178,8 +164,8 @@
       </desc>
     </func>
     <func>
-      <name>no_debug(Name)</name>
-      <name>no_debug(Name,Timeout) -> void()</name>
+      <name name="no_debug" arity="1"/>
+      <name name="no_debug" arity="2"/>
       <fsummary>Turn off debugging</fsummary>
       <desc>
         <p>Turns off all debugging for the process. This includes
@@ -188,8 +174,8 @@
       </desc>
     </func>
     <func>
-      <name>suspend(Name)</name>
-      <name>suspend(Name,Timeout) -> void()</name>
+      <name name="suspend" arity="1"/>
+      <name name="suspend" arity="2"/>
       <fsummary>Suspend the process</fsummary>
       <desc>
         <p>Suspends the process. When the process is suspended, it
@@ -198,49 +184,37 @@
       </desc>
     </func>
     <func>
-      <name>resume(Name)</name>
-      <name>resume(Name,Timeout) -> void()</name>
+      <name name="resume" arity="1"/>
+      <name name="resume" arity="2"/>
       <fsummary>Resume a suspended process</fsummary>
       <desc>
         <p>Resumes a suspended process.</p>
       </desc>
     </func>
     <func>
-      <name>change_code(Name, Module, OldVsn, Extra)</name>
-      <name>change_code(Name, Module, OldVsn, Extra, Timeout) -> ok | {error, Reason}</name>
+      <name name="change_code" arity="4"/>
+      <name name="change_code" arity="5"/>
       <fsummary>Send the code change system message to the process</fsummary>
-      <type>
-        <v>OldVsn = undefined | term()</v>
-        <v>Module = atom()</v>
-        <v>Extra = term()</v>
-      </type>
       <desc>
         <p>Tells the process to change code. The process must be
-          suspended to handle this message. The <c>Extra</c> argument is
+          suspended to handle this message. The <c><anno>Extra</anno></c> argument is
           reserved for each process to use as its own. The function
-          <c>Mod:system_code_change/4</c> is called. <c>OldVsn</c> is
-          the old version of the <c>Module</c>.</p>
+          <c><anno>Module</anno>:system_code_change/4</c> is called. <c><anno>OldVsn</anno></c> is
+          the old version of the <c><anno>Module</anno></c>.</p>
       </desc>
     </func>
     <func>
-      <name>get_status(Name)</name>
-      <name>get_status(Name,Timeout) -> {status, Pid, {module, Mod}, [PDict, SysState, Parent, Dbg, Misc]}</name>
+      <name name="get_status" arity="1"/>
+      <name name="get_status" arity="2"/>
       <fsummary>Get the status of the process</fsummary>
-      <type>
-        <v>PDict = [{Key, Value}]</v>
-        <v>SysState = running | suspended</v>
-        <v>Parent = pid()</v>
-        <v>Dbg = [dbg_opt()]</v>
-        <v>Misc = term()</v>
-      </type>
       <desc>
         <p>Gets the status of the process.</p>
-        <p>The value of <c>Misc</c> varies for different types of
+        <p>The value of <c><anno>Misc</anno></c> varies for different types of
           processes. For example, a <c>gen_server</c> process returns
           the callback module's state, and a <c>gen_fsm</c> process
           returns information such as its current state name. Callback
           modules for <c>gen_server</c> and <c>gen_fsm</c> can also
-          customise the value of <c>Misc</c> by exporting
+          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>
@@ -249,17 +223,9 @@
       </desc>
     </func>
     <func>
-      <name>install(Name,{Func,FuncState})</name>
-      <name>install(Name,{Func,FuncState},Timeout)</name>
+      <name name="install" arity="2"/>
+      <name name="install" arity="3"/>
       <fsummary>Install a debug function in the process</fsummary>
-      <type>
-        <v>Func = dbg_fun()</v>
-        <v>dbg_fun() = fun(FuncState, Event, ProcState) -> done | NewFuncState</v>
-        <v>FuncState = term()</v>
-        <v>Event = system_event()</v>
-        <v>ProcState = term()</v>
-        <v>NewFuncState = term()</v>
-      </type>
       <desc>
         <p>This function makes it possible to install other debug
           functions than the ones defined above. An example of such a
@@ -267,22 +233,19 @@
           special event and performs some action when the event is
           generated. This could, for example, be turning on low level tracing.
           </p>
-        <p><c>Func</c> is called whenever a system event is
+        <p><c><anno>Func</anno></c> is called whenever a system event is
           generated. This function should return <c>done</c>, or a new
           func state. In the first case, the function is removed. It is removed 
           if the function fails.</p>
       </desc>
     </func>
     <func>
-      <name>remove(Name,Func)</name>
-      <name>remove(Name,Func,Timeout) -> void()</name>
+      <name name="remove" arity="2"/>
+      <name name="remove" arity="3"/>
       <fsummary>Remove a debug function from the process</fsummary>
-      <type>
-        <v>Func = dbg_fun()</v>
-      </type>
       <desc>
         <p>Removes a previously installed debug function from the
-          process. <c>Func</c> must be the same as previously
+          process. <c><anno>Func</anno></c> must be the same as previously
           installed.</p>
       </desc>
     </func>
@@ -296,86 +259,65 @@
   </section>
   <funcs>
     <func>
-      <name>debug_options(Options) -> [dbg_opt()]</name>
+      <name name="debug_options" arity="1"/>
       <fsummary>Convert a list of options to a debug structure</fsummary>
-      <type>
-        <v>Options = [Opt]</v>
-        <v>Opt = trace | log | statistics | {log_to_file, FileName} | {install, {Func, FuncState}}</v>
-        <v>Func = dbg_fun()</v>
-        <v>FuncState = term()</v>
-      </type>
       <desc>
         <p>This function can be used by a process that initiates a debug
           structure from a list of options. The values of the
-          <c>Opt</c> argument are the same as the corresponding
+          <c><anno>Opt</anno></c> argument are the same as the corresponding
           functions.</p>
       </desc>
     </func>
     <func>
-      <name>get_debug(Item,Debug,Default) -> term()</name>
+      <name name="get_debug" arity="3"/>
       <fsummary>Get the data associated with a debug option</fsummary>
-      <type>
-        <v>Item = log | statistics</v>
-        <v>Debug = [dbg_opt()]</v>
-        <v>Default = term()</v>
-      </type>
       <desc>
-        <p>This function gets the data associated with a debug option. <c>Default</c> is returned if the
-          <c>Item</c> is not found.  Can be
+        <p>This function gets the data associated with a debug option. <c><anno>Default</anno></c> is returned if the
+          <c><anno>Item</anno></c> is not found.  Can be
           used by the process to retrieve debug data for printing
           before it terminates.</p>
       </desc>
     </func>
     <func>
-      <name>handle_debug([dbg_opt()],FormFunc,Extra,Event) -> [dbg_opt()]</name>
+      <name name="handle_debug" arity="4"/>
       <fsummary>Generate a system event</fsummary>
-      <type>
-        <v>FormFunc = dbg_fun()</v>
-        <v>Extra = term()</v>
-        <v>Event = system_event()</v>
-      </type>
       <desc>
-        <p>This function is called by a process when it generates a system event. <c>FormFunc</c> is a formatting function which is called as <c>FormFunc(Device, Event, Extra)</c> in order to print the events, which is necessary if tracing is activated. <c>Extra</c> is any
-          extra information which the process needs in the format function, for example the name of the process.</p>
+        <p>This function is called by a process when it generates a
+           system event. <c><anno>FormFunc</anno></c> is a formatting
+           function which is called as <c><anno>FormFunc</anno>(Device,
+           <anno>Event</anno>, <anno>Extra</anno>)</c> in order to print
+           the events, which is necessary if tracing is activated.
+           <c><anno>Extra</anno></c> is any extra information which the
+           process needs in the format function, for example the name
+           of the process.</p>
       </desc>
     </func>
     <func>
-      <name>handle_system_msg(Msg,From,Parent,Module,Debug,Misc)</name>
+      <name name="handle_system_msg" arity="6"/>
       <fsummary>Take care of system messages</fsummary>
-      <type>
-        <v>Msg = term()</v>
-        <v>From = pid()</v>
-        <v>Parent = pid()</v>
-        <v>Module = atom()</v>
-        <v>Debug = [dbg_opt()]</v>
-        <v>Misc = term()</v>
-      </type>
       <desc>
         <p>This function is used by a process module that wishes to take care of system
-          messages. The process receives a <c>{system, From, Msg}</c>
-          message and passes the <c>Msg</c> and <c>From</c> to this
+          messages. The process receives a <c>{system, <anno>From</anno>, <anno>Msg</anno>}</c>
+          message and passes the <c><anno>Msg</anno></c> and <c><anno>From</anno></c> to this
           function.
           </p>
         <p>This function <em>never</em> returns. It calls the function
-          <c>Module:system_continue(Parent, NDebug, Misc)</c> where the
+          <c><anno>Module</anno>:system_continue(<anno>Parent</anno>, NDebug, <anno>Misc</anno>)</c> where the
           process continues the execution, or
-          <c>Module:system_terminate(Reason, Parent, Debug, Misc)</c> if
-          the process should terminate. The <c>Module</c> must export
+          <c><anno>Module</anno>:system_terminate(Reason, <anno>Parent</anno>, <anno>Debug</anno>, <anno>Misc</anno>)</c> if
+          the process should terminate. The <c><anno>Module</anno></c> must export
           <c>system_continue/3</c>, <c>system_terminate/4</c>, and
           <c>system_code_change/4</c> (see below).
           </p>
-        <p>The <c>Misc</c> argument can be used to save internal data
+        <p>The <c><anno>Misc</anno></c> argument can be used to save internal data
           in a process, for example its state. It is sent to
-          <c>Module:system_continue/3</c> or
-          <c>Module:system_terminate/4</c></p>
+          <c><anno>Module</anno>:system_continue/3</c> or
+          <c><anno>Module</anno>:system_terminate/4</c></p>
       </desc>
     </func>
     <func>
-      <name>print_log(Debug) -> void()</name>
+      <name name="print_log" arity="1"/>
       <fsummary>Print the logged events in the debug structure</fsummary>
-      <type>
-        <v>Debug = [dbg_opt()]</v>
-      </type>
       <desc>
         <p>Prints the logged system events in the debug structure
           using <c>FormFunc</c> as defined when the event was
@@ -383,11 +325,11 @@
       </desc>
     </func>
     <func>
-      <name>Mod:system_continue(Parent, Debug, Misc)</name>
+      <name>Mod:system_continue(Parent, Debug, Misc) -> none()</name>
       <fsummary>Called when the process should continue its execution</fsummary>
       <type>
         <v>Parent = pid()</v>
-        <v>Debug = [dbg_opt()]</v>
+        <v>Debug = [<seealso marker="#type-dbg_opt">dbg_opt()</seealso>]</v>
         <v>Misc = term()</v>
       </type>
       <desc>
@@ -397,12 +339,12 @@
       </desc>
     </func>
     <func>
-      <name>Mod:system_terminate(Reason, Parent, Debug, Misc)</name>
+      <name>Mod:system_terminate(Reason, Parent, Debug, Misc) -> none()</name>
       <fsummary>Called when the process should terminate</fsummary>
       <type>
         <v>Reason = term()</v>
         <v>Parent = pid()</v>
-        <v>Debug = [dbg_opt()]</v>
+        <v>Debug = [<seealso marker="#type-dbg_opt">dbg_opt()</seealso>]</v>
         <v>Misc = term()</v>
       </type>
       <desc>