Merge branch 'bjorn/stdlib/doc'

* bjorn/stdlib/doc:
  Update STDLIB documentation

1 files changed, 224 insertions, 191 deletions

diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml
index f02b1f0651..58ca5644cf 100644
--- a/lib/stdlib/doc/src/proc_lib.xml
+++ b/lib/stdlib/doc/src/proc_lib.xml
@@ -29,44 +29,55 @@
     <rev></rev>
   </header>
   <module>proc_lib</module>
-  <modulesummary>Functions for asynchronous and synchronous start of processes adhering to the OTP design principles.</modulesummary>
+  <modulesummary>Functions for asynchronous and synchronous start of processes
+    adhering to the OTP design principles.</modulesummary>
   <description>
     <p>This module is used to start processes adhering to
-      the <seealso marker="doc/design_principles:des_princ">OTP Design Principles</seealso>. Specifically, the functions in this
-      module are used by the OTP standard behaviors (<c>gen_server</c>,
-      <c>gen_fsm</c>, <c>gen_statem</c>, ...) when starting new processes.
-      The functions can also be used to start <em>special processes</em>,
-      user defined processes which comply to the OTP design principles. See
-      <seealso marker="doc/design_principles:spec_proc">Sys and Proc_Lib</seealso> in OTP Design Principles for an example.</p>
+      the <seealso marker="doc/design_principles:des_princ">
+      OTP Design Principles</seealso>. Specifically, the functions in this
+      module are used by the OTP standard behaviors (for example,
+      <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_statem</c>)
+      when starting new processes. The functions
+      can also be used to start <em>special processes</em>, user-defined
+      processes that comply to the OTP design principles. For an example,
+      see section <seealso marker="doc/design_principles:spec_proc">
+      sys and proc_lib</seealso> in OTP Design Principles.</p>
+
+
     <p>Some useful information is initialized when a process starts.
       The registered names, or the process identifiers, of the parent
       process, and the parent ancestors, are stored together with
       information about the function initially called in the process.</p>
-    <p>While in "plain Erlang" a process is said to terminate normally
-      only for the exit reason <c>normal</c>, a process started
+
+    <p>While in "plain Erlang", a process is said to terminate normally
+      only for exit reason <c>normal</c>, a process started
       using <c>proc_lib</c> is also said to terminate normally if it
       exits with reason <c>shutdown</c> or <c>{shutdown,Term}</c>.
       <c>shutdown</c> is the reason used when
       an application (supervision tree) is stopped.</p>
-    <p>When a process started using <c>proc_lib</c> terminates
-      abnormally -- that is, with another exit reason than <c>normal</c>,
-      <c>shutdown</c>, or <c>{shutdown,Term}</c> -- a <em>crash report</em>
-      is generated, which is written to terminal by the default SASL
+
+    <p>When a process that is started using <c>proc_lib</c> terminates
+      abnormally (that is, with another exit reason than <c>normal</c>,
+      <c>shutdown</c>, or <c>{shutdown,Term}</c>), a <em>crash report</em>
+      is generated, which is written to terminal by the default <c>SASL</c>
       event handler. That is, the crash report is normally only visible
-      if the SASL application is started. See
-      <seealso marker="sasl:sasl_app">sasl(6)</seealso> and
-      <seealso marker="sasl:error_logging">SASL User's Guide</seealso>.</p>
-    <p>The crash report contains the previously stored information such
+      if the <c>SASL</c> application is started; see
+      <seealso marker="sasl:sasl_app"><c>sasl(6)</c></seealso> and section
+      <seealso marker="sasl:error_logging">SASL Error Logging</seealso>
+      in the SASL User's Guide.</p>
+
+    <p>The crash report contains the previously stored information, such
       as ancestors and initial function, the termination reason, and
-      information regarding other processes which terminate as a result
+      information about other processes that terminate as a result
       of this process terminating.</p>
   </description>
+
   <datatypes>
     <datatype>
       <name name="spawn_option"/>
       <desc>
         <p>See <seealso marker="erts:erlang#spawn_opt/4">
-          erlang:spawn_opt/2,3,4,5</seealso>.</p>
+          <c>erlang:spawn_opt/2,3,4,5</c></seealso>.</p>
       </desc>
     </datatype>
     <datatype>
@@ -83,8 +94,129 @@
       <name name="dict_or_pid"/>
     </datatype>
   </datatypes>
+
   <funcs>
     <func>
+      <name name="format" arity="1"/>
+      <fsummary>Format a crash report.</fsummary>
+      <desc>
+        <p>Equivalent to <seealso marker="#format/2">
+          <c>format(<anno>CrashReport</anno>, latin1)</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="format" arity="2"/>
+      <fsummary>Format a crash report.</fsummary>
+      <desc>
+        <p>This function can be used by a user-defined event handler to
+          format a crash report. The crash report is sent using
+          <seealso marker="kernel:error_logger#error_report/2">
+          <c>error_logger:error_report(crash_report,
+          <anno>CrashReport</anno>)</c></seealso>.
+          That is, the event to be handled is of the format
+          <c>{error_report, GL, {Pid, crash_report,
+          <anno>CrashReport</anno>}}</c>,
+          where <c>GL</c> is the group leader pid of process
+          <c>Pid</c> that sent the crash report.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="format" arity="3"/>
+      <fsummary>Format a crash report.</fsummary>
+      <desc>
+        <p>This function can be used by a user-defined event handler to
+          format a crash report. When <anno>Depth</anno> is specified as a
+          positive integer, it is used in the format string to
+          limit the output as follows: <c>io_lib:format("~P",
+          [Term,<anno>Depth</anno>])</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="hibernate" arity="3"/>
+      <fsummary>Hibernate a process until a message is sent to it.</fsummary>
+      <desc>
+        <p>This function does the same as (and does call) the
+          <seealso marker="erts:erlang#erlang:hibernate/3">
+          <c>hibernate/3</c></seealso> BIF,
+          but ensures that exception handling and logging continues to
+          work as expected when the process wakes up.</p>
+        <p>Always use this function instead of the BIF for processes started
+          using <c>proc_lib</c> functions.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="init_ack" arity="1"/>
+      <name name="init_ack" arity="2"/>
+      <fsummary>Used by a process when it has started.</fsummary>
+      <desc>
+        <p>This function must be used by a process that has been started by
+          a <seealso marker="#start/3"><c>start[_link]/3,4,5</c></seealso>
+          function. It tells <c><anno>Parent</anno></c> that the process has
+          initialized itself, has started, or has failed to initialize
+          itself.</p>
+        <p>Function <c>init_ack/1</c> uses the parent value
+          previously stored by the start function used.</p>
+        <p>If this function is not called, the start function
+          returns an error tuple (if a link and/or a time-out is used) or
+          hang otherwise.</p>
+        <p>The following example illustrates how this function and
+          <c>proc_lib:start_link/3</c> are used:</p>
+        <code type="none">
+-module(my_proc).
+-export([start_link/0]).
+-export([init/1]).
+
+start_link() ->
+    proc_lib:start_link(my_proc, init, [self()]).
+
+init(Parent) ->
+    case do_initialization() of
+        ok ->
+            proc_lib:init_ack(Parent, {ok, self()});
+        {error, Reason} ->
+            exit(Reason)
+    end,
+    loop().
+
+...</code>
+      </desc>
+    </func>
+
+    <func>
+      <name name="initial_call" arity="1"/>
+      <fsummary>Extract the initial call of a <c>proc_lib</c>spawned process.
+      </fsummary>
+      <desc>
+        <p>Extracts the initial call of a process that was started
+          using one of the spawn or start functions in this module.
+          <c><anno>Process</anno></c> can either be a pid, an integer tuple
+          (from which a pid can be created), or the process information of a
+          process <c>Pid</c> fetched through an
+          <c>erlang:process_info(Pid)</c> function call.</p>
+        <note>
+          <p>The list <c><anno>Args</anno></c> no longer contains the
+            arguments, but the same number of atoms as the number of arguments;
+            the first atom is <c>'Argument__1'</c>, the second
+            <c>'Argument__2'</c>, and so on. The reason is that the argument
+            list could waste a significant amount of memory, and if the
+            argument list contained funs, it could be impossible to upgrade the
+            code for the module.</p>
+          <p>If the process was spawned using a fun, <c>initial_call/1</c> no
+            longer returns the fun, but the module, function for the
+            local function implementing the fun, and the arity, for example,
+            <c>{some_module,-work/3-fun-0-,0}</c> (meaning that the fun was
+            created in function <c>some_module:work/3</c>). The reason is that
+            keeping the fun would prevent code upgrade for the module, and that
+            a significant amount of memory could be wasted.</p>
+        </note>
+      </desc>
+    </func>
+
+    <func>
       <name name="spawn" arity="1"/>
       <name name="spawn" arity="2"/>
       <name name="spawn" arity="3"/>
@@ -96,11 +228,12 @@
       <type variable="Function"/>
       <type variable="Args"/>
       <desc>
-        <p>Spawns a new process and initializes it as described above.
-          The process is spawned using the
-          <seealso marker="erts:erlang#spawn/1">spawn</seealso> BIFs.</p>
+        <p>Spawns a new process and initializes it as described in the
+          beginning of this manual page. The process is spawned using the
+          <seealso marker="erts:erlang#spawn/1"><c>spawn</c></seealso> BIFs.</p>
       </desc>
     </func>
+
     <func>
       <name name="spawn_link" arity="1"/>
       <name name="spawn_link" arity="2"/>
@@ -113,18 +246,19 @@
       <type variable="Function"/>
       <type variable="Args"/>
       <desc>
-        <p>Spawns a new process and initializes it as described above.
-          The process is spawned using the
-          <seealso marker="erts:erlang#spawn_link/1">spawn_link</seealso>
+        <p>Spawns a new process and initializes it as described in the
+          beginning of this manual page. The process is spawned using the
+          <seealso marker="erts:erlang#spawn_link/1"><c>spawn_link</c></seealso>
           BIFs.</p>
       </desc>
     </func>
+
     <func>
       <name name="spawn_opt" arity="2"/>
       <name name="spawn_opt" arity="3"/>
       <name name="spawn_opt" arity="4"/>
       <name name="spawn_opt" arity="5"/>
-      <fsummary>Spawn a new process with given options.</fsummary>
+      <fsummary>Spawn a new process with specified options.</fsummary>
       <type variable="Node"/>
       <type variable="Fun" name_i="1"/>
       <type variable="Module"/>
@@ -132,17 +266,18 @@
       <type variable="Args"/>
       <type variable="SpawnOpts"/>
       <desc>
-        <p>Spawns a new process and initializes it as described above.
-          The process is spawned using the
-          <seealso marker="erts:erlang#spawn_opt/2">spawn_opt</seealso>
+        <p>Spawns a new process and initializes it as described in the
+          beginning of this manual page. The process is spawned using the
+          <seealso marker="erts:erlang#spawn_opt/2"><c>spawn_opt</c></seealso>
           BIFs.</p>
         <note>
-          <p>Using the spawn option <c>monitor</c> is currently not
-            allowed, but will cause the function to fail with reason
+          <p>Using spawn option <c>monitor</c> is not
+            allowed. It causes the function to fail with reason
             <c>badarg</c>.</p>
         </note>
       </desc>
     </func>
+
     <func>
       <name name="start" arity="3"/>
       <name name="start" arity="4"/>
@@ -153,151 +288,94 @@
       <fsummary>Start a new process synchronously.</fsummary>
       <desc>
         <p>Starts a new process synchronously. Spawns the process and
-          waits for it to start.  When the process has started, it
+          waits for it to start. When the process has started, it
           <em>must</em> call
-          <seealso marker="#init_ack/2">init_ack(Parent,Ret)</seealso>
-          or <seealso marker="#init_ack/1">init_ack(Ret)</seealso>,
+          <seealso marker="#init_ack/2"><c>init_ack(Parent, Ret)</c></seealso>
+          or <seealso marker="#init_ack/1"><c>init_ack(Ret)</c></seealso>,
           where <c>Parent</c> is the process that evaluates this
-          function.  At this time, <c>Ret</c> is returned.</p>
-        <p>If the <c>start_link/3,4,5</c> function is used and
+          function. At this time, <c>Ret</c> is returned.</p>
+        <p>If function <c>start_link/3,4,5</c> is used and
           the process crashes before it has called <c>init_ack/1,2</c>,
-          <c>{error, <anno>Reason</anno>}</c> is returned if the calling process
-          traps exits.</p>
-        <p>If <c><anno>Time</anno></c> is specified as an integer, this function
-          waits for <c><anno>Time</anno></c> milliseconds for the new process to call
-          <c>init_ack</c>, or <c>{error, timeout}</c> is returned, and
-          the process is killed.</p>
-        <p>The <c><anno>SpawnOpts</anno></c> argument, if given, will be passed
-          as the last argument to the <c>spawn_opt/2,3,4,5</c> BIF.</p>
+          <c>{error, <anno>Reason</anno>}</c> is returned if the calling
+          process traps exits.</p>
+        <p>If <c><anno>Time</anno></c> is specified as an integer, this
+          function waits for <c><anno>Time</anno></c> milliseconds for the
+          new process to call <c>init_ack</c>, or <c>{error, timeout}</c> is
+          returned, and the process is killed.</p>
+        <p>Argument <c><anno>SpawnOpts</anno></c>, if specified, is passed
+          as the last argument to the <seealso marker="erts:erlang#spawn_opt/2">
+          <c>spawn_opt/2,3,4,5</c></seealso> BIF.</p>
         <note>
-          <p>Using the spawn option <c>monitor</c> is currently not
-            allowed, but will cause the function to fail with reason
+          <p>Using spawn option <c>monitor</c> is not
+            allowed. It causes the function to fail with reason
             <c>badarg</c>.</p>
         </note>
       </desc>
     </func>
-    <func>
-      <name name="init_ack" arity="1"/>
-      <name name="init_ack" arity="2"/>
-      <fsummary>Used by a process when it has started.</fsummary>
-      <desc>
-        <p>This function must be used by a process that has been started by
-          a <seealso marker="#start/3">start[_link]/3,4,5</seealso>
-          function. It tells <c><anno>Parent</anno></c> that the process has
-          initialized itself, has started, or has failed to initialize
-          itself.</p>
-        <p>The <c>init_ack/1</c> function uses the parent value
-          previously stored by the start function used.</p>
-        <p>If this function is not called, the start function will
-          return an error tuple (if a link and/or a timeout is used) or
-          hang otherwise.</p>
-        <p>The following example illustrates how this function and
-          <c>proc_lib:start_link/3</c> are used.</p>
-        <code type="none">
--module(my_proc).
--export([start_link/0]).
--export([init/1]).
 
-start_link() ->
-    proc_lib:start_link(my_proc, init, [self()]).
-
-init(Parent) ->
-    case do_initialization() of
-        ok ->
-            proc_lib:init_ack(Parent, {ok, self()});
-        {error, Reason} ->
-            exit(Reason)
-    end,
-    loop().
-
-...</code>
-      </desc>
-    </func>
     <func>
-      <name name="format" arity="1"/>
-      <fsummary>Format a crash report.</fsummary>
-      <desc>
-        <p>Equivalent to <c>format(<anno>CrashReport</anno>, latin1)</c>.</p>
-      </desc>
-    </func>
-    <func>
-      <name name="format" arity="2"/>
-      <fsummary>Format a crash report.</fsummary>
+      <name name="stop" arity="1"/>
+      <fsummary>Terminate a process synchronously.</fsummary>
+      <type variable="Process"/>
       <desc>
-        <p>This function can be used by a user defined event handler to
-          format a crash report. The crash report is sent using
-          <c>error_logger:error_report(crash_report, <anno>CrashReport</anno>)</c>.
-          That is, the event to be handled is of the format
-          <c>{error_report, GL, {Pid, crash_report, <anno>CrashReport</anno>}}</c>
-          where <c>GL</c> is the group leader pid of the process
-          <c>Pid</c> which sent the crash report.</p>
+        <p>Equivalent to <seealso marker="#stop/3">
+          <c>stop(Process, normal, infinity)</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="format" arity="3"/>
-      <fsummary>Format a crash report.</fsummary>
+      <name name="stop" arity="3"/>
+      <fsummary>Terminate a process synchronously.</fsummary>
+      <type variable="Process"/>
+      <type variable="Reason"/>
+      <type variable="Timeout"/>
       <desc>
-        <p>This function can be used by a user defined event handler to
-          format a crash report. When <anno>Depth</anno> is given as an
-	  positive integer, it will be used in the format string to
-	  limit the output as follows: <c>io_lib:format("~P",
-	  [Term,<anno>Depth</anno>])</c>.</p>
+        <p>Orders the process to exit with the specified <c>Reason</c> and
+          waits for it to terminate.</p>
+        <p>Returns <c>ok</c> if the process exits with
+          the specified <c>Reason</c> within <c>Timeout</c> milliseconds.</p>
+        <p>If the call times out, a <c>timeout</c> exception is raised.</p>
+        <p>If the process does not exist, a <c>noproc</c>
+          exception is raised.</p>
+        <p>The implementation of this function is based on the
+          <c>terminate</c> system message, and requires that the
+          process handles system messages correctly.
+          For information about system messages, see
+          <seealso marker="sys"><c>sys(3)</c></seealso> and section
+          <seealso marker="doc/design_principles:spec_proc">
+          sys and proc_lib</seealso> in OTP Design Principles.</p>
       </desc>
     </func>
-    <func>
-      <name name="initial_call" arity="1"/>
-      <fsummary>Extract the initial call of a <c>proc_lib</c>spawned process.</fsummary>
-      <desc>
-        <p>Extracts the initial call of a process that was started
-          using one of the spawn or start functions described above.
-          <c><anno>Process</anno></c> can either be a pid, an integer tuple (from
-          which a pid can be created), or the process information of a
-          process <c>Pid</c> fetched through an
-          <c>erlang:process_info(Pid)</c> function call.</p>
-
-	<note><p>The list <c><anno>Args</anno></c> no longer contains the actual arguments,
-	but the same number of atoms as the number of arguments; the first atom
-	is always <c>'Argument__1'</c>, the second <c>'Argument__2'</c>, and
-	so on. The reason is that the argument list could waste a significant
-	amount of memory, and if the argument list contained funs, it could
-	be impossible to upgrade the code for the module.</p>
 
-	<p>If the process was spawned using a fun, <c>initial_call/1</c> no
-	longer returns the actual fun, but the module, function for the local
-	function implementing the fun, and the arity, for instance
-	<c>{some_module,-work/3-fun-0-,0}</c> (meaning that the fun was
-	created in the function <c>some_module:work/3</c>).
-	The reason is that keeping the fun would prevent code upgrade for the
-	module, and that a significant amount of memory could be wasted.</p>
-	</note>
-      </desc>
-    </func>
     <func>
       <name name="translate_initial_call" arity="1"/>
-      <fsummary>Extract and translate the initial call of a <c>proc_lib</c>spawned process.</fsummary>
+      <fsummary>Extract and translate the initial call of a
+        <c>proc_lib</c>spawned process.</fsummary>
       <desc>
-        <p>This function is used by the <c>c:i/0</c> and
-          <c>c:regs/0</c> functions in order to present process
-          information.</p>
-        <p>Extracts the initial call of a process that was started
-          using one of the spawn or start functions described above,
-          and translates it to more useful information. <c><anno>Process</anno></c>
+        <p>This function is used by functions
+          <seealso marker="c#i/0"><c>c:i/0</c></seealso> and
+          <seealso marker="c#regs/0"><c>c:regs/0</c></seealso>
+          to present process information.</p>
+        <p>This function extracts the initial call of a process that was
+          started using one of the spawn or start functions in this module,
+          and translates it to more useful information.
+          <c><anno>Process</anno></c>
           can either be a pid, an integer tuple (from which a pid can
           be created), or the process information of a process
           <c>Pid</c> fetched through an <c>erlang:process_info(Pid)</c>
           function call.</p>
-        <p>If the initial call is to one of the system defined behaviors
+        <p>If the initial call is to one of the system-defined behaviors
           such as <c>gen_server</c> or <c>gen_event</c>, it is
           translated to more useful information. If a <c>gen_server</c>
           is spawned, the returned <c><anno>Module</anno></c> is the name of
           the callback module and <c><anno>Function</anno></c> is <c>init</c>
           (the function that initiates the new server).</p>
         <p>A <c>supervisor</c> and a <c>supervisor_bridge</c> are also
-          <c>gen_server</c> processes. In order to return information
+          <c>gen_server</c> processes. To return information
           that this process is a supervisor and the name of the
-          call-back module, <c><anno>Module</anno></c> is <c>supervisor</c> and
+          callback module, <c><anno>Module</anno></c> is <c>supervisor</c> and
           <c><anno>Function</anno></c> is the name of the supervisor callback
-          module. <c><anno>Arity</anno></c> is <c>1</c> since the <c>init/1</c>
+          module. <c><anno>Arity</anno></c> is <c>1</c>, as the <c>init/1</c>
           function is called initially in the callback module.</p>
         <p>By default, <c>{proc_lib,init_p,5}</c> is returned if no
           information about the initial call can be found. It is
@@ -305,57 +383,12 @@ init(Parent) ->
           spawned with the <c>proc_lib</c> module.</p>
       </desc>
     </func>
-    <func>
-      <name name="hibernate" arity="3"/>
-      <fsummary>Hibernate a process until a message is sent to it</fsummary>
-      <desc>
-        <p>This function does the same as (and does call) the BIF
-          <seealso marker="erts:erlang#erlang:hibernate/3">hibernate/3</seealso>,
-          but ensures that exception handling and logging continues to
-          work as expected when the process wakes up. Always use this
-          function instead of the BIF for processes started using
-          <c>proc_lib</c> functions.</p>
-      </desc>
-    </func>
-    <func>
-      <name name="stop" arity="1"/>
-      <fsummary>Terminate a process synchronously.</fsummary>
-      <type variable="Process"/>
-      <desc>
-	<p>Equivalent to <seealso marker="#stop/3">stop(Process,
-	    normal, infinity)</seealso>.</p>
-      </desc>
-    </func>
-    <func>
-      <name name="stop" arity="3"/>
-      <fsummary>Terminate a process synchronously.</fsummary>
-      <type variable="Process"/>
-      <type variable="Reason"/>
-      <type variable="Timeout"/>
-      <desc>
-        <p>Orders the process to exit with the given <c>Reason</c> and
-          waits for it to terminate.</p>
-	<p>The function returns <c>ok</c> if the process exits with
-	  the given <c>Reason</c> within <c>Timeout</c>
-	  milliseconds.</p>
-	<p>If the call times out, a <c>timeout</c> exception is
-	  raised.</p>
-	<p>If the process does not exist, a <c>noproc</c>
-	  exception is raised.</p>
-	<p>The implementation of this function is based on the
-	  <c>terminate</c> system message, and requires that the
-	  process handles system messages  correctly.
-	  See <seealso marker="sys">sys(3)</seealso>
-	  and <seealso marker="doc/design_principles:spec_proc">OTP
-	  Design Principles</seealso> for information about system
-	  messages.</p>
-      </desc>
-    </func>
   </funcs>
 
   <section>
-    <title>SEE ALSO</title>
-    <p><seealso marker="kernel:error_logger">error_logger(3)</seealso></p>
+    <title>See Also</title>
+    <p><seealso marker="kernel:error_logger">
+      <c>error_logger(3)</c></seealso></p>
   </section>
 </erlref>