Merge branch 'bjorn/kernel/doc'

* bjorn/kernel/doc:
  code: Remove 'bad_path' error code from set_path/1
  Update Kernel documentation

1 files changed, 90 insertions, 78 deletions

diff --git a/lib/kernel/doc/src/app.xml b/lib/kernel/doc/src/app.xml
index 35feec144e..3740f1cff9 100644
--- a/lib/kernel/doc/src/app.xml
+++ b/lib/kernel/doc/src/app.xml
@@ -42,12 +42,12 @@
   </description>
 
   <section>
-    <title>FILE SYNTAX</title>
-    <p>The application resource file should be called
-      <c>Application.app</c> where <c>Application</c> is the name of
-      the application. The file should be located in the <c>ebin</c>
-      directory for the application.</p>
-    <p>It must contain one single Erlang term, which is called an
+    <title>File Syntax</title>
+    <p>The application resource file is to be called
+      <c>Application.app</c>, where <c>Application</c> is the
+      application name. The file is to be located in directory <c>ebin</c>
+      for the application.</p>
+    <p>The file must contain a single Erlang term, which is called an
       <em>application specification</em>:</p>
     <code type="none">
 {application, Application,
@@ -80,19 +80,26 @@ Env          [{Par,Val}]          []
 Start        {Module,StartArgs}   []
 Phases       [{Phase,PhaseArgs}]  undefined
 RTDeps       [ApplicationVersion] []
-  Module = Name = App = Par = Phase = atom()
-  Val = StartArgs = PhaseArgs = term()
-  ApplicationVersion = string()</code>
-    <p><c>Application</c> is the name of the application.</p>
+
+Module = Name = App = Par = Phase = atom()
+Val = StartArgs = PhaseArgs = term()
+ApplicationVersion = string()</code>
+    <taglist>
+      <tag><c>Application</c></tag>
+      <item>Application name.</item>
+    </taglist>
     <p>For the application controller, all keys are optional.
       The respective default values are used for any omitted keys.</p>
     <p>The functions in <c>systools</c> require more information. If
-      they are used, the following keys are mandatory:
-      <c>description</c>, <c>vsn</c>, <c>modules</c>, <c>registered</c>
-      and <c>applications</c>. The other keys are ignored by
-      <c>systools</c>.</p>
-      <warning><p>The <c>RTDeps</c> type was introduced in OTP 17.0 and
-      might be subject to changes during the OTP 17 release.</p></warning>
+      they are used, the following keys are mandatory:</p>
+    <list type="bulleted">
+      <item><c>description</c></item>
+      <item><c>vsn</c></item>
+      <item><c>modules</c></item>
+      <item><c>registered</c></item>
+      <item><c>applications</c></item>
+    </list>
+    <p>The other keys are ignored by <c>systools</c>.</p>
     <taglist>
       <tag><c>description</c></tag>
       <item>
@@ -104,7 +111,7 @@ RTDeps       [ApplicationVersion] []
       </item>
       <tag><c>vsn</c></tag>
       <item>
-        <p>The version of the application.</p>
+        <p>Version of the application.</p>
       </item>
       <tag><c>modules</c></tag>
       <item>
@@ -114,15 +121,14 @@ RTDeps       [ApplicationVersion] []
       </item>
       <tag><c>maxP</c></tag>
       <item>
-        <p><em>Deprecated - will be ignored</em>          <br></br>
-
-          The maximum number of processes allowed in the application.</p>
+        <p><em>Deprecated - is ignored</em></p>
+        <p>Maximum number of processes allowed in the application.</p>
       </item>
       <tag><c>maxT</c></tag>
       <item>
-        <p>The maximum time in milliseconds that the application is
-          allowed to run. After the specified time the application will
-          automatically terminate.</p>
+        <p>Maximum time, in milliseconds, that the application is
+          allowed to run. After the specified time, the application
+          terminates automatically.</p>
       </item>
       <tag><c>registered</c></tag>
       <item>
@@ -132,20 +138,20 @@ RTDeps       [ApplicationVersion] []
       </item>
       <tag><c>included_applications</c></tag>
       <item>
-        <p>All applications which are included by this application.
-          When this application is started, all included application
-          will automatically be loaded, but not started, by
-          the application controller. It is assumed that the topmost
+        <p>All applications included by this application.
+          When this application is started, all included applications
+          are loaded automatically, but not started, by
+          the application controller. It is assumed that the top-most
           supervisor of the included application is started by a
           supervisor of this application.</p>
       </item>
       <tag><c>applications</c></tag>
       <item>
-        <p>All applications which must be started before this
+        <p>All applications that must be started before this
           application is allowed to be started. <c>systools</c> uses
           this list to generate correct start scripts. Defaults to
-          the empty list, but note that all applications have
-          dependencies to (at least) <c>kernel</c> and <c>stdlib</c>.</p>
+          the empty list, but notice that all applications have
+          dependencies to (at least) <c>Kernel</c> and <c>STDLIB</c>.</p>
       </item>
       <tag><c>env</c></tag>
       <item>
@@ -153,78 +159,84 @@ RTDeps       [ApplicationVersion] []
           of a configuration parameter is retrieved by calling
           <c>application:get_env/1,2</c>. The values in the application
           resource file can be overridden by values in a configuration
-          file (see <c>config(4)</c>) or by command line flags (see
-          <c>erl(1)</c>).</p>
+          file (see <seealso marker="config"><c>config(4)</c></seealso>)
+          or by command-line flags (see
+          <seealso marker="erts:erl"><c>erts:erl(1)</c></seealso>).</p>
       </item>
       <tag><c>mod</c></tag>
       <item>
-        <p>Specifies the application callback module and a start
-          argument, see <c>application(3)</c>.</p>
-        <p>The <c>mod</c> key is necessary for an application
-          implemented as a supervision tree, or the application
-          controller will not know how to start it. The <c>mod</c> key
+        <p>Specifies the application callback module and a start argument, see
+          <seealso marker="application"><c>application(3)</c></seealso>.</p>
+        <p>Key <c>mod</c> is necessary for an application
+          implemented as a supervision tree, otherwise the application
+          controller does not know how to start it. <c>mod</c>
           can be omitted for applications without processes, typically
-          code libraries such as the application STDLIB.</p>
+          code libraries, for example, <c>STDLIB</c>.</p>
       </item>
       <tag><c>start_phases</c></tag>
       <item>
         <p>A list of start phases and corresponding start arguments for
           the application. If this key is present, the application
-          master will - in addition to the usual call to
-          <c>Module:start/2</c> - also call
+          master, in addition to the usual call to
+          <c>Module:start/2</c>, also calls
           <c>Module:start_phase(Phase,Type,PhaseArgs)</c> for each
-          start phase defined by the <c>start_phases</c> key, and only
-          after this extended start procedure will
-          <c>application:start(Application)</c> return.</p>
-        <p>Start phases may be used to synchronize startup of an
+          start phase defined by key <c>start_phases</c>. Only
+          after this extended start procedure,
+          <c>application:start(Application)</c> returns.</p>
+        <p>Start phases can be used to synchronize startup of an
           application and its included applications. In this case,
-          the <c>mod</c> key must be specified as:</p>
+          key <c>mod</c> must be specified as follows:</p>
         <code type="none">
 {mod, {application_starter,[Module,StartArgs]}}</code>
-        <p>The application master will then call <c>Module:start/2</c>
+        <p>The application master then calls <c>Module:start/2</c>
           for the primary application, followed by calls to
           <c>Module:start_phase/3</c> for each start phase (as defined
-          for the primary application) both for the primary application
-          and for each of its included application, for which the start
+          for the primary application), both for the primary application
+          and for each of its included applications, for which the start
           phase is defined.</p>
         <p>This implies that for an included application, the set of
           start phases must be a subset of the set of phases defined
-          for the primary application. Refer to <em>OTP Design Principles</em> for more information.</p>
+          for the primary application. For more information, see
+          <seealso marker="doc/design_principles:applications">OTP Design Principles</seealso>.
+        </p>
       </item>
-      <tag><marker id="runtime_dependencies"></marker><c>runtime_dependencies</c></tag>
-      <item><p>A list of application versions that the application
-      depends on. An example of such an application version is
-      <c>"kernel-3.0"</c>. Application versions specified as runtime
-      dependencies are minimum requirements. That is, a larger
-      application version than the one specified in the
-      dependency satisfies the requirement. For information on
-      how to compare application versions see
-      <seealso marker="doc/system_principles:versions">the
-      documentation of versions in the system principles
-      guide</seealso>. Note that the application version
-      specifies a source code version. An additional indirect
-      requirement is that installed binary application of
-      the specified version has been built so that it is
-      compatible with the rest of the system.</p>
-      <p>Some dependencies might only be required in specific runtime
-      scenarios. In the case such optional dependencies exist, these are
-      specified and documented in the corresponding "App" documentation
-      of the specific application.</p>
-      <warning><p>The <c>runtime_dependencies</c> key was introduced in
-      OTP 17.0. The type of its value might be subject to changes during
-      the OTP 17 release.</p></warning>
-      <warning><p>All runtime dependencies specified in OTP applications
-      during the OTP 17 release may not be completely correct. This
-      is actively being worked on. Declared runtime dependencies in OTP
-      applications are expected to be correct in OTP 18.</p></warning>
+      <tag>
+        <marker id="runtime_dependencies"></marker>
+        <c>runtime_dependencies</c></tag>
+      <item>
+        <p>A list of application versions that the application
+          depends on. An example of such an application version is
+          <c>"kernel-3.0"</c>. Application versions specified as runtime
+          dependencies are minimum requirements. That is, a larger
+          application version than the one specified in the
+          dependency satisfies the requirement. For information about
+          how to compare application versions, see section
+          <seealso marker="doc/system_principles:versions">Versions</seealso>
+          in the System Principles User's Guide.</p>
+        <p>Notice that the application version
+          specifies a source code version. One more, indirect,
+          requirement is that the installed binary application of
+          the specified version is built so that it is
+          compatible with the rest of the system.</p>
+        <p>Some dependencies can only be required in specific runtime
+          scenarios. When such optional dependencies exist, these are
+          specified and documented in the corresponding "App" documentation
+          of the specific application.</p>
+	  <warning><p>The <c>runtime_dependencies</c> key was introduced in
+	  OTP 17.0. The type of its value might be subject to changes during
+	  the OTP 17 release.</p></warning>
+	  <warning><p>All runtime dependencies specified in OTP applications
+	  during the OTP 17 release may not be completely correct. This
+	  is actively being worked on. Declared runtime dependencies in OTP
+	  applications are expected to be correct in OTP 18.</p></warning>
       </item>
     </taglist>
   </section>
 
   <section>
-    <title>SEE ALSO</title>
-    <p><seealso marker="application">application(3)</seealso>,
-      systools(3)</p>
+    <title>See Also</title>
+    <p><seealso marker="application"><c>application(3)</c></seealso>,
+      <seealso marker="sasl:systools"><c>sasl:systools(3)</c></seealso></p>
   </section>
 </fileref>