r

Use Erlang specs and types for documentation

1 files changed, 102 insertions, 116 deletions

diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml
index d6203bdaa0..009aa60faa 100644
--- a/lib/stdlib/doc/src/supervisor.xml
+++ b/lib/stdlib/doc/src/supervisor.xml
@@ -199,51 +199,81 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules}
       </item>
     </list>
   </section>
+  <datatypes>
+    <datatype>
+      <name name="child"/>
+    </datatype>
+    <datatype>
+      <name name="child_id"/>
+      <desc><p>Not a <c>pid()</c>.</p></desc>
+    </datatype>
+    <datatype>
+      <name name="child_spec"/>
+    </datatype>
+    <datatype>
+      <name name="mfargs"/>
+      <desc><p><c>A</c> (the argument list) has the value
+         <c>undefined</c> if <c>Restart</c> is <c>temporary</c>.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="modules"/>
+    </datatype>
+    <datatype>
+      <name name="restart"/>
+    </datatype>
+    <datatype>
+      <name name="shutdown"/>
+    </datatype>
+    <datatype>
+      <name name="strategy"/>
+    </datatype>
+    <datatype>
+      <name name="sup_ref"/>
+    </datatype>
+    <datatype>
+      <name name="worker"/>
+    </datatype>
+  </datatypes>
   <funcs>
     <func>
-      <name>start_link(Module, Args) -> Result</name>
-      <name>start_link(SupName, Module, Args) -> Result</name>
+      <name name="start_link" arity="2"/>
+      <name name="start_link" arity="3"/>
       <fsummary>Create a supervisor process.</fsummary>
-      <type>
-        <v>SupName = {local,Name} | {global,Name}</v>
-        <v>&nbsp;Name = atom()</v>
-        <v>Module = atom()</v>
-        <v>Args = term()</v>
-        <v>Result = {ok,Pid} | ignore | {error,Error}</v>
-        <v>&nbsp;Pid = pid()</v>
-        <v>&nbsp;Error = {already_started,Pid}} | shutdown | term()</v>
-      </type>
+      <type name="startlink_ret"/>
+      <type name="startlink_err"/>
+      <type name="sup_name"/>
       <desc>
         <p>Creates a supervisor process as part of a supervision tree.
           The function will, among other things, ensure that
           the supervisor is linked to the calling process (its
           supervisor).</p>
-        <p>The created supervisor process calls <c>Module:init/1</c> to
+        <p>The created supervisor process calls <c><anno>Module</anno>:init/1</c> to
           find out about restart strategy, maximum restart frequency
           and child processes. To ensure a synchronized start-up
           procedure, <c>start_link/2,3</c> does not return until
-          <c>Module:init/1</c> has returned and all child processes
+          <c><anno>Module</anno>:init/1</c> has returned and all child processes
           have been started.</p>
-        <p>If <c>SupName={local,Name}</c> the supervisor is registered
+        <p>If <c><anno>SupName</anno>={local,Name}</c> the supervisor is registered
           locally as <c>Name</c> using <c>register/2</c>. If
-          <c>SupName={global,Name}</c> the supervisor is registered
+          <c><anno>SupName</anno>={global,Name}</c> the supervisor is registered
           globally as <c>Name</c> using <c>global:register_name/2</c>.
           If no name is provided, the supervisor is not registered.</p>
-        <p><c>Module</c> is the name of the callback module.</p>
-        <p><c>Args</c> is an arbitrary term which is passed as
-          the argument to <c>Module:init/1</c>.</p>
+        <p><c><anno>Module</anno></c> is the name of the callback module.</p>
+        <p><c><anno>Args</anno></c> is an arbitrary term which is passed as
+          the argument to <c><anno>Module</anno>:init/1</c>.</p>
         <p>If the supervisor and its child processes are successfully
           created (i.e. if all child process start functions return
           <c>{ok,Child}</c>, <c>{ok,Child,Info}</c>, or <c>ignore</c>)
           the function returns <c>{ok,Pid}</c>, where <c>Pid</c> is
           the pid of the supervisor. If there already exists a process
-          with the specified <c>SupName</c> the function returns
+          with the specified <c><anno>SupName</anno></c> the function returns
           <c>{error,{already_started,Pid}}</c>, where <c>Pid</c> is
           the pid of that process.</p>
-        <p>If <c>Module:init/1</c> returns <c>ignore</c>, this function
+        <p>If <c><anno>Module</anno>:init/1</c> returns <c>ignore</c>, this function
           returns <c>ignore</c> as well and the supervisor terminates
           with reason <c>normal</c>.
-          If <c>Module:init/1</c> fails or returns an incorrect value,
+          If <c><anno>Module</anno>:init/1</c> fails or returns an incorrect value,
           this function returns <c>{error,Term}</c> where <c>Term</c>
           is a term with information about the error, and the supervisor
           terminates with reason <c>Term</c>.</p>
@@ -255,21 +285,15 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules}
       </desc>
     </func>
     <func>
-      <name>start_child(SupRef, ChildSpec) -> Result</name>
+      <name name="start_child" arity="2"/>
       <fsummary>Dynamically add a child process to a supervisor.</fsummary>
-      <type>
-        <v>SupRef = Name | {Name,Node} | {global,Name} | pid()</v>
-        <v>&nbsp;Name = Node = atom()</v>
-        <v>ChildSpec = child_spec() | [term()]</v>
-        <v>Result = {ok,Child} | {ok,Child,Info} | {error,Error}</v>
-        <v>&nbsp;Child = pid() | undefined</v>
-        <v>&nbsp;Info = term()</v>
-        <v>&nbsp;Error = already_present | {already_started,Child} | term()</v>
-      </type>
+      <type name="child_spec"/>
+      <type name="startchild_ret"/>
+      <type name="startchild_err"/>
       <desc>
         <p>Dynamically adds a child specification to the supervisor
-          <c>SupRef</c> which starts the corresponding child process.</p>
-        <p><c>SupRef</c> can be:</p>
+          <c><anno>SupRef</anno></c> which starts the corresponding child process.</p>
+        <p><marker id="SupRef"><c><anno>SupRef</anno></c></marker> can be:</p>
         <list type="bulleted">
           <item>the pid,</item>
           <item><c>Name</c>, if the supervisor is locally registered,</item>
@@ -278,26 +302,26 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules}
           <item><c>{global,Name}</c>, if the supervisor is globally
            registered.</item>
         </list>
-        <p><c>ChildSpec</c> should be a valid child specification
+        <p><c><anno>ChildSpec</anno></c> should be a valid child specification
           (unless the supervisor is a <c>simple_one_for_one</c>
           supervisor, see below). The child process will be started by
           using the start function as defined in the child
           specification.</p>
         <p>If the case of a <c>simple_one_for_one</c> supervisor,
           the child specification defined in <c>Module:init/1</c> will
-          be used and <c>ChildSpec</c> should instead be an arbitrary
-          list of terms <c>List</c>. The child process will then be
-          started by appending <c>List</c> to the existing start
+          be used and <c><anno>ChildSpec</anno></c> should instead be an arbitrary
+          list of terms <c><anno>List</anno></c>. The child process will then be
+          started by appending <c><anno>List</anno></c> to the existing start
           function arguments, i.e. by calling
-          <c>apply(M, F, A++List)</c> where <c>{M,F,A}</c> is the start
+          <c>apply(M, F, A++<anno>List</anno>)</c> where <c>{M,F,A}</c> is the start
           function defined in the child specification.</p>
         <p>If there already exists a child specification with
-          the specified <c>Id</c>, <c>ChildSpec</c> is discarded and
+          the specified <c><anno>Id</anno></c>, <c><anno>ChildSpec</anno></c> is discarded and
           the function returns <c>{error,already_present}</c> or
-          <c>{error,{already_started,Child}}</c>, depending on if
+          <c>{error,{already_started,<anno>Child</anno>}}</c>, depending on if
           the corresponding child process is running or not.</p>
-        <p>If the child process start function returns <c>{ok,Child}</c>
-          or <c>{ok,Child,Info}</c>, the child specification and pid is
+        <p>If the child process start function returns <c>{ok,<anno>Child</anno>}</c>
+          or <c>{ok,<anno>Child</anno>,<anno>Info</anno>}</c>, the child specification and pid is
           added to the supervisor and the function returns the same
           value.</p>
         <p>If the child process start function returns <c>ignore</c>,
@@ -312,27 +336,20 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules}
       </desc>
     </func>
     <func>
-      <name>terminate_child(SupRef, Id) -> Result</name>
+      <name name="terminate_child" arity="2"/>
       <fsummary>Terminate a child process belonging to a supervisor.</fsummary>
-      <type>
-        <v>SupRef = Name | {Name,Node} | {global,Name} | pid()</v>
-        <v>&nbsp;Name = Node = atom()</v>
-        <v>Id = pid() | term()</v>
-        <v>Result = ok | {error,Error}</v>
-        <v>&nbsp;Error = not_found | simple_one_for_one</v>
-      </type>
       <desc>
-        <p>Tells the supervisor <c>SupRef</c> to terminate the given
+        <p>Tells the supervisor <c><anno>SupRef</anno></c> to terminate the given
           child.</p>
         <p>If the supervisor is not <c>simple_one_for_one</c>,
-          <c>Id</c> must be the child specification identifier. The
+          <c><anno>Id</anno></c> must be the child specification identifier. The
           process, if there is one, is terminated but the child
           specification is kept by the supervisor. The child process
           may later be restarted by the supervisor. The child process
           can also be restarted explicitly by calling
           <c>restart_child/2</c>. Use <c>delete_child/2</c> to remove
           the child specification.</p>
-        <p>If the supervisor is <c>simple_one_for_one</c>, <c>Id</c>
+        <p>If the supervisor is <c>simple_one_for_one</c>, <c><anno>Id</anno></c>
           must be the child process' <c>pid()</c>. I the specified
           process is alive, but is not a child of the given
           supervisor, the function will return
@@ -340,119 +357,93 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules}
           identifier is given instead instead of a <c>pid()</c>, the
           function will return <c>{error,simple_one_for_one}</c>.</p>
         <p>If successful, the function returns <c>ok</c>. If there is
-          no child specification with the specified <c>Id</c>, the
+          no child specification with the specified <c><anno>Id</anno></c>, the
           function returns <c>{error,not_found}</c>.</p>
         <p>See <c>start_child/2</c> for a description of
-          <c>SupRef</c>.</p>
+          <c><anno>SupRef</anno></c>.</p>
       </desc>
     </func>
     <func>
-      <name>delete_child(SupRef, Id) -> Result</name>
+      <name name="delete_child" arity="2"/>
       <fsummary>Delete a child specification from a supervisor.</fsummary>
-      <type>
-        <v>SupRef = Name | {Name,Node} | {global,Name} | pid()</v>
-        <v>&nbsp;Name = Node = atom()</v>
-        <v>Id = term()</v>
-        <v>Result = ok | {error,Error}</v>
-        <v>&nbsp;Error = running | not_found | simple_one_for_one</v>
-      </type>
       <desc>
-        <p>Tells the supervisor <c>SupRef</c> to delete the child
-          specification identified by <c>Id</c>. The corresponding child
+        <p>Tells the supervisor <c><anno>SupRef</anno></c> to delete the child
+          specification identified by <c><anno>Id</anno></c>. The corresponding child
           process must not be running, use <c>terminate_child/2</c> to
           terminate it.</p>
-        <p>See <c>start_child/2</c> for a description of <c>SupRef</c>.</p>
+        <p>See <seealso marker="#SupRef"><c>start_child/2</c></seealso> for a description of
+          <c>SupRef</c>.</p>
         <p>If successful, the function returns <c>ok</c>. If the child
-          specification identified by <c>Id</c> exists but
+          specification identified by <c><anno>Id</anno></c> exists but
           the corresponding child process is running, the function
           returns <c>{error,running}</c>. If the child specification
-          identified by <c>Id</c> does not exist, the function returns
+          identified by <c><anno>Id</anno></c> does not exist, the function returns
           <c>{error,not_found}</c>.</p>
       </desc>
     </func>
     <func>
-      <name>restart_child(SupRef, Id) -> Result</name>
+      <name name="restart_child" arity="2"/>
       <fsummary>Restart a terminated child process belonging to a supervisor.</fsummary>
-      <type>
-        <v>SupRef = Name | {Name,Node} | {global,Name} | pid()</v>
-        <v>&nbsp;Name = Node = atom()</v>
-        <v>Id = term()</v>
-        <v>Result = {ok,Child} | {ok,Child,Info} | {error,Error}</v>
-        <v>&nbsp;Child = pid() | undefined</v>
-        <v>&nbsp;Error = running | not_found | simple_one_for_one | term()</v>
-      </type>
       <desc>
-        <p>Tells the supervisor <c>SupRef</c> to restart a child process
+        <p>Tells the supervisor <c><anno>SupRef</anno></c> to restart a child process
           corresponding to the child specification identified by
-          <c>Id</c>. The child specification must exist and
+          <c><anno>Id</anno></c>. The child specification must exist and
           the corresponding child process must not be running.</p>
-        <p>See <c>start_child/2</c> for a description of <c>SupRef</c>.</p>
-        <p>If the child specification identified by <c>Id</c> does not
+        <p>See <seealso marker="#SupRef"><c>start_child/2</c></seealso> for a description of
+          <c>SupRef</c>.</p>
+        <p>If the child specification identified by <c><anno>Id</anno></c> does not
           exist, the function returns <c>{error,not_found}</c>. If
           the child specification exists but the corresponding process
           is already running, the function returns
           <c>{error,running}</c>.</p>
-        <p>If the child process start function returns <c>{ok,Child}</c>
-          or <c>{ok,Child,Info}</c>, the pid is added to the supervisor
+        <p>If the child process start function returns <c>{ok,<anno>Child</anno>}</c>
+          or <c>{ok,<anno>Child</anno>,<anno>Info</anno>}</c>, the pid is added to the supervisor
           and the function returns the same value.</p>
         <p>If the child process start function returns <c>ignore</c>,
           the pid remains set to <c>undefined</c> and the function
           returns <c>{ok,undefined}</c>.</p>
         <p>If the child process start function returns an error tuple or
           an erroneous value, or if it fails, the function returns
-          <c>{error,Error}</c> where <c>Error</c> is a term containing
+          <c>{error,<anno>Error</anno>}</c> where <c><anno>Error</anno></c> is a term containing
           information about the error.</p>
       </desc>
     </func>
     <func>
-      <name>which_children(SupRef) -> [{Id,Child,Type,Modules}]</name>
+      <name name="which_children" arity="1"/>
       <fsummary>Return information about all children specifications and child processes belonging to a supervisor.</fsummary>
-      <type>
-        <v>SupRef = Name | {Name,Node} | {global,Name} | pid()</v>
-        <v>&nbsp;Name = Node = atom()</v>
-        <v>Id = term() | undefined</v>
-        <v>Child = pid() | undefined</v>
-        <v>Type = worker | supervisor</v>
-        <v>Modules = [Module] | dynamic</v>
-        <v>&nbsp;Module = atom()</v>
-      </type>
       <desc>
         <p>Returns a newly created list with information about all child
           specifications and child processes belonging to
-          the supervisor <c>SupRef</c>.</p>
+          the supervisor <c><anno>SupRef</anno></c>.</p>
         <p>Note that calling this function when supervising a large
           number of children under low memory conditions can cause an
           out of memory exception.</p>
-        <p>See <c>start_child/2</c> for a description of <c>SupRef</c>.</p>
+        <p>See <seealso marker="#SupRef"><c>start_child/2</c></seealso> for a description of
+          <c>SupRef</c>.</p>
         <p>The information given for each child specification/process
           is:</p>
         <list type="bulleted">
           <item>
-            <p><c>Id</c> - as defined in the child specification or
+            <p><c><anno>Id</anno></c> - as defined in the child specification or
               <c>undefined</c> in the case of a
               <c>simple_one_for_one</c> supervisor.</p>
           </item>
           <item>
-            <p><c>Child</c> - the pid of the corresponding child
+            <p><c><anno>Child</anno></c> - the pid of the corresponding child
               process, or <c>undefined</c> if there is no such process.</p>
           </item>
           <item>
-            <p><c>Type</c> - as defined in the child specification.</p>
+            <p><c><anno>Type</anno></c> - as defined in the child specification.</p>
           </item>
           <item>
-            <p><c>Modules</c> - as defined in the child specification.</p>
+            <p><c><anno>Modules</anno></c> - as defined in the child specification.</p>
           </item>
         </list>
       </desc>
     </func>
     <func>
-      <name>count_children(SupRef) -> PropListOfCounts</name>
+      <name name="count_children" arity="1"/>
       <fsummary>Return counts for the number of childspecs, active children, supervisors and workers.</fsummary>
-      <type>
-        <v>SupRef = Name | {Name,Node} | {global,Name} | pid()</v>
-        <v>&nbsp;Name = Node = atom()</v>
-        <v>PropListOfCounts = [{specs, ChildSpecCount}, {active, ActiveProcessCount}, {supervisors, ChildSupervisorCount}, {workers, ChildWorkerCount}]</v>
-      </type>
       <desc>
         <p>Returns a property list (see <c>proplists</c>) containing the
           counts for each of the following elements of the supervisor's
@@ -479,17 +470,12 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules}
       </desc>
     </func>
     <func>
-      <name>check_childspecs([ChildSpec]) -> Result</name>
+      <name name="check_childspecs" arity="1"/>
       <fsummary>Check if children specifications are syntactically correct.</fsummary>
-      <type>
-        <v>ChildSpec = child_spec()</v>
-        <v>Result = ok | {error,Error}</v>
-        <v>&nbsp;Error = term()</v>
-      </type>
       <desc>
         <p>This function takes a list of child specification as argument
           and returns <c>ok</c> if all of them are syntactically
-          correct, or <c>{error,Error}</c> otherwise.</p>
+          correct, or <c>{error,<anno>Error</anno>}</c> otherwise.</p>
       </desc>
     </func>
   </funcs>
@@ -506,9 +492,9 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules}
       <type>
         <v>Args = term()</v>
         <v>Result = {ok,{{RestartStrategy,MaxR,MaxT},[ChildSpec]}} | ignore</v>
-        <v>&nbsp;RestartStrategy = one_for_all | one_for_one | rest_for_one | simple_one_for_one</v>
-        <v>&nbsp;MaxR = MaxT = int()>=0</v>
-        <v>&nbsp;ChildSpec = child_spec()</v>
+        <v>&nbsp;RestartStrategy = <seealso marker="#type-strategy">strategy()</seealso></v>
+        <v>&nbsp;MaxR = MaxT = integer()>=0</v>
+        <v>&nbsp;ChildSpec = <seealso marker="#type-child_spec">child_spec()</seealso></v>
       </type>
       <desc>
         <p>Whenever a supervisor is started using