Merge branch 'bjorn/kernel/doc'

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

1 files changed, 98 insertions, 77 deletions

diff --git a/lib/kernel/doc/src/global_group.xml b/lib/kernel/doc/src/global_group.xml
index 4b21b0a14a..8f947b9adf 100644
--- a/lib/kernel/doc/src/global_group.xml
+++ b/lib/kernel/doc/src/global_group.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1998</year><year>2013</year>
+      <year>1998</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -26,22 +26,22 @@
     <prepared>Esko Vierum&auml;ki</prepared>
     <docno></docno>
     <date>1998-12-18</date>
-    <rev>b</rev>
+    <rev>B</rev>
   </header>
   <module>global_group</module>
-  <modulesummary>Grouping Nodes to Global Name Registration Groups</modulesummary>
+  <modulesummary>Grouping nodes to global name registration groups.</modulesummary>
   <description>
-    <p>The global group function makes it possible to group the nodes
-      in a system into partitions, each partition having its own global
-      name space, refer to <c>global(3)</c>. These partitions are
-      called global groups.</p>
-    <p>The main advantage of dividing systems to global groups is that
+    <p>This module makes it possible to partition the nodes of a
+      system into <em>global groups</em>. Each global group has its own
+      global namespace, see <seealso marker="global">
+      <c>global(3)</c></seealso>.</p>
+    <p>The main advantage of dividing systems into global groups is that
       the background load decreases while the number of nodes to be
       updated is reduced when manipulating globally registered names.</p>
     <p>The Kernel configuration parameter <c>global_groups</c> defines
       the global groups (see also
-      <seealso marker="kernel_app">kernel(6)</seealso>,
-      <seealso marker="config">config(4)</seealso>:</p>
+      <seealso marker="kernel_app#global_groups"><c>kernel(6)</c></seealso>
+      and <seealso marker="config"><c>config(4)</c></seealso>):</p>
     <code type="none">
 {global_groups, [GroupTuple :: group_tuple()]}</code>
     <p>For the processes and nodes to run smoothly using the global
@@ -54,22 +54,24 @@
       </item>
       <item>
         <p>All involved nodes must agree on the global group definition,
-          or the behavior of the system is undefined.</p>
+          otherwise the behavior of the system is undefined.</p>
       </item>
       <item>
-        <p><em>All</em> nodes in the system should belong to exactly
+        <p><em>All</em> nodes in the system must belong to exactly
           one global group.</p>
       </item>
     </list>
-    <p>In the following description, a <em>group node</em> is a node
+    <p>In the following descriptions, a <em>group node</em> is a node
       belonging to the same global group as the local node.</p>
   </description>
-  <datatypes>
+
+ <datatypes>
     <datatype>
       <name name="group_tuple"/>
       <desc>
         <p>A <c>GroupTuple</c> without <c>PublishType</c> is the same as a
-          <c>GroupTuple</c> with <c>PublishType == normal</c>.</p>
+          <c>GroupTuple</c> with <c>PublishType</c> equal to <c>normal</c>.
+	</p>
       </desc>
     </datatype>
     <datatype>
@@ -78,52 +80,57 @@
     <datatype>
       <name name="publish_type"/>
       <desc>
-        <p>A node started with the command line flag <c>-hidden</c>, see
-          <seealso marker="erts:erl">erl(1)</seealso>, is said to be a
-          <em>hidden</em> node. A hidden node will establish hidden
+        <p>A node started with command-line flag <c>-hidden</c> (see
+          <seealso marker="erts:erl"><c>erl(1)</c></seealso>) is said
+          to be a <em>hidden</em> node. A hidden node establishes hidden
           connections to nodes not part of the same global group, but
           normal (visible) connections to nodes part of the same global
           group.</p>
-        <p>A global group defined with <c>PublishType == hidden</c>, is
-          said to be a hidden global group. All nodes in a hidden global
-          group are hidden nodes, regardless if they are started with
-          the <c>-hidden</c> command line flag or not.</p>
+        <p>A global group defined with <c>PublishType</c> equal to
+	  <c>hidden</c> is said to be a hidden global group.
+	  All nodes in a hidden global
+          group are hidden nodes, whether they are started with
+          command-line flag <c>-hidden</c> or not.</p>
       </desc>
     </datatype>
     <datatype>
       <name name="name"/>
       <desc><p>A registered name.</p></desc>
     </datatype>
+
     <datatype>
       <name name="where"/>
     </datatype>
   </datatypes>
+
   <funcs>
     <func>
       <name name="global_groups" arity="0"/>
-      <fsummary>Return the global group names</fsummary>
+      <fsummary>Return the global group names.</fsummary>
       <desc>
-        <p>Returns a tuple containing the name of the global group
+        <p>Returns a tuple containing the name of the global group that
           the local node belongs to, and the list of all other known
           group names. Returns <c>undefined</c> if no global groups are
           defined.</p>
       </desc>
     </func>
+
     <func>
       <name name="info" arity="0"/>
-      <fsummary>Information about global groups</fsummary>
+      <fsummary>Information about global groups.</fsummary>
       <type name="info_item"/>
       <type name="sync_state"/>
       <desc>
         <p>Returns a list containing information about the global
-          groups. Each element of the list is a tuple. The order of
-          the tuples is not defined.</p>
+          groups. Each list element is a tuple. The order of
+          the tuples is undefined.</p>
         <taglist>
           <tag><c>{state, <anno>State</anno>}</c></tag>
           <item>
             <p>If the local node is part of a global group,
-              <c><anno>State</anno> == synced</c>. If no global groups are defined,
-              <c><anno>State</anno> == no_conf</c>.</p>
+              <c><anno>State</anno></c> is equal to <c>synced</c>.
+              If no global groups are defined,
+              <c><anno>State</anno></c> is equal to <c>no_conf</c>.</p>
           </item>
           <tag><c>{own_group_name, <anno>GroupName</anno>}</c></tag>
           <item>
@@ -152,117 +159,131 @@
           <tag><c>{other_groups, <anno>Groups</anno>}</c></tag>
           <item>
             <p><c><anno>Groups</anno></c> is a list of tuples
-              <c>{<anno>GroupName</anno>, <anno>Nodes</anno>}</c>, specifying the name and nodes
+              <c>{<anno>GroupName</anno>, <anno>Nodes</anno>}</c>,
+              specifying the name and nodes
               of the other global groups.</p>
           </item>
           <tag><c>{monitoring, <anno>Pids</anno>}</c></tag>
           <item>
-            <p>A list of pids, specifying the processes which have
+            <p>A list of pids, specifying the processes that have
               subscribed to <c>nodeup</c> and <c>nodedown</c> messages.</p>
           </item>
         </taglist>
       </desc>
     </func>
+
     <func>
       <name name="monitor_nodes" arity="1"/>
-      <fsummary>Subscribe to node status changes</fsummary>
+      <fsummary>Subscribe to node status changes.</fsummary>
       <desc>
-        <p>Depending on <c><anno>Flag</anno></c>, the calling process starts
-          subscribing (<c><anno>Flag</anno> == true</c>) or stops subscribing
-          (<c><anno>Flag</anno> == false</c>) to node status change messages.</p>
-        <p>A process which has subscribed will receive the messages
+        <p>Depending on <c><anno>Flag</anno></c>, the calling process
+          starts subscribing (<c><anno>Flag</anno></c> equal to
+          <c>true</c>) or stops subscribing (<c><anno>Flag</anno></c>
+          equal to <c>false</c>) to node status change messages.</p>
+        <p>A process that has subscribed receives the messages
           <c>{nodeup, Node}</c> and <c>{nodedown, Node}</c> when a
           group node connects or disconnects, respectively.</p>
       </desc>
     </func>
+
     <func>
       <name name="own_nodes" arity="0"/>
-      <fsummary>Return the group nodes</fsummary>
+      <fsummary>Return the group nodes.</fsummary>
       <desc>
         <p>Returns the names of all group nodes, regardless of their
           current status.</p>
       </desc>
     </func>
+
     <func>
       <name name="registered_names" arity="1"/>
-      <fsummary>Return globally registered names</fsummary>
+      <fsummary>Return globally registered names.</fsummary>
       <desc>
-        <p>Returns a list of all names which are globally registered
+        <p>Returns a list of all names that are globally registered
           on the specified node or in the specified global group.</p>
       </desc>
     </func>
+
     <func>
       <name name="send" arity="2"/>
       <name name="send" arity="3"/>
-      <fsummary>Send a message to a globally registered pid</fsummary>
+      <fsummary>Send a message to a globally registered pid.</fsummary>
       <desc>
         <p>Searches for <c><anno>Name</anno></c>, globally registered on
-          the specified node or in the specified global group, or --
-          if the <c><anno>Where</anno></c> argument is not provided -- in any global
-          group. The global groups are searched in the order in which
-          they appear in the value of the <c>global_groups</c>
-          configuration parameter.</p>
-        <p>If <c><anno>Name</anno></c> is found, the message <c><anno>Msg</anno></c> is sent to
+          the specified node or in the specified global group, or
+          (if argument <c><anno>Where</anno></c> is not provided) in any
+          global group. The global groups are searched in the order that
+          they appear in the value of configuration parameter
+          <c>global_groups</c>.</p>
+        <p>If <c><anno>Name</anno></c> is found, message
+          <c><anno>Msg</anno></c> is sent to
           the corresponding pid. The pid is also the return value of
           the function. If the name is not found, the function returns
           <c>{badarg, {<anno>Name</anno>, <anno>Msg</anno>}}</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="sync" arity="0"/>
-      <fsummary>Synchronize the group nodes</fsummary>
+      <fsummary>Synchronize the group nodes.</fsummary>
       <desc>
         <p>Synchronizes the group nodes, that is, the global name
-          servers on the group nodes. Also check the names globally
+          servers on the group nodes. Also checks the names globally
           registered in the current global group and unregisters them
           on any known node not part of the group.</p>
         <p>If synchronization is not possible, an error report is sent
-          to the error logger (see also <c>error_logger(3)</c>).</p>
-        <p>Failure:
-          <c>{error, {'invalid global_groups definition', Bad}}</c> if
-          the <c>global_groups</c> configuration parameter has an
+          to the error logger (see also
+          <seealso marker="error_logger"><c>error_logger(3)</c></seealso>.
+        </p>
+        <p>Returns <c>{error, {'invalid global_groups definition', Bad}}</c>
+          if configuration parameter <c>global_groups</c> has an
           invalid value <c>Bad</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="whereis_name" arity="1"/>
       <name name="whereis_name" arity="2"/>
-      <fsummary>Get the pid with a given globally registered name</fsummary>
+      <fsummary>Get the pid with a specified globally registered name.</fsummary>
       <desc>
         <p>Searches for <c><anno>Name</anno></c>, globally registered on
-          the specified node or in the specified global group, or -- if
-          the <c><anno>Where</anno></c> argument is not provided -- in any global
-          group. The global groups are searched in the order in which
-          they appear in the value of the <c>global_groups</c>
-          configuration parameter.</p>
-        <p>If <c><anno>Name</anno></c> is found, the corresponding pid is returned.
-          If the name is not found, the function returns
+          the specified node or in the specified global group, or
+          (if argument <c><anno>Where</anno></c> is not provided) in any global
+          group. The global groups are searched in the order that
+          they appear in the value of configuration parameter
+          <c>global_groups</c>.</p>
+        <p>If <c><anno>Name</anno></c> is found, the corresponding pid is
+          returned. If the name is not found, the function returns
           <c>undefined</c>.</p>
       </desc>
     </func>
   </funcs>
 
   <section>
-    <title>NOTE</title>
-    <p>In the situation where a node has lost its connections to other
-      nodes in its global group, but has connections to nodes in other
-      global groups, a request from another global group may produce an
-      incorrect or misleading result. For example, the isolated node may
-      not have accurate information about registered names in its
-      global group.</p>
-    <p>Note also that the <c>send/2,3</c> function is not secure.</p>
-    <p>Distribution of applications is highly dependent of the global
-      group definitions. It is not recommended that an application is 
-      distributed over several global groups of the obvious reason that
-      the registered names may be moved to another global group at
-      failover/takeover. There is nothing preventing doing this, but
-      the application code must in such case handle the situation.</p>
+    <title>Notes</title>
+    <list type="bulleted">
+      <item><p>In the situation where a node has lost its connections to other
+        nodes in its global group, but has connections to nodes in other
+        global groups, a request from another global group can produce an
+        incorrect or misleading result. For example, the isolated node can
+        have inaccurate information about registered names in its
+        global group.</p></item>
+     <item><p>Function
+       <seealso marker="#send/2"><c>send/2,3</c></seealso>
+       is not secure.</p></item>
+     <item><p>Distribution of applications is highly dependent of the global
+        group definitions. It is not recommended that an application is
+        distributed over many global groups, as
+        the registered names can be moved to another global group at
+        failover/takeover. Nothing prevents this to be done, but
+        the application code must then handle the situation.</p></item>
+    </list>
   </section>
 
   <section>
-    <title>SEE ALSO</title>
-    <p><seealso marker="erts:erl">erl(1)</seealso>,
-      <seealso marker="global">global(3)</seealso></p>
+    <title>See Also</title>
+    <p><seealso marker="global"><c>global(3)</c></seealso>,
+      <seealso marker="erts:erl"><c>erl(1)</c></seealso></p>
   </section>
 </erlref>