Use Erlang specs and types for documentation

1 files changed, 70 insertions, 87 deletions

diff --git a/lib/kernel/doc/src/global_group.xml b/lib/kernel/doc/src/global_group.xml
index 4facf4a4aa..abf6178fc4 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>2009</year>
+      <year>1998</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -42,26 +42,7 @@
       <seealso marker="kernel_app">kernel(6)</seealso>,
       <seealso marker="config">config(4)</seealso>:</p>
     <code type="none">
-{global_groups, [GroupTuple]}</code>
-    <p>Types:</p>
-    <list type="bulleted">
-      <item><c>GroupTuple = {GroupName, [Node]} | {GroupName, PublishType, [Node]}</c></item>
-      <item><c>GroupName = atom()</c> (naming a global group)</item>
-      <item><c>PublishType = normal | hidden</c></item>
-      <item><c>Node = atom()</c> (naming a node)</item>
-    </list>
-    <p>A <c>GroupTuple</c> without <c>PublishType</c> is the same as a
-      <c>GroupTuple</c> with <c>PublishType == normal</c>.</p>
-    <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
-      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>
+{global_groups, [GroupTuple :: group_tuple()]}</code>
     <p>For the processes and nodes to run smoothly using the global
       group functionality, the following criteria must be met:</p>
     <list type="bulleted">
@@ -82,14 +63,44 @@
     <p>In the following description, a <em>group node</em> is a node
       belonging to the same global group as the local node.</p>
   </description>
+  <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>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="group_name"/>
+    </datatype>
+    <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
+          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>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="name"/>
+      <desc><p>A registered name.</p></desc>
+    </datatype>
+    <datatype>
+      <name name="where"/>
+    </datatype>
+  </datatypes>
   <funcs>
     <func>
-      <name>global_groups() -> {GroupName, GroupNames} | undefined</name>
+      <name name="global_groups" arity="0"/>
       <fsummary>Return the global group names</fsummary>
-      <type>
-        <v>GroupName = atom()</v>
-        <v>GroupNames = [GroupName]</v>
-      </type>
       <desc>
         <p>Returns a tuple containing the name of the global group
           the local node belongs to, and the list of all other known
@@ -98,53 +109,52 @@
       </desc>
     </func>
     <func>
-      <name>info() -> [{Item, Info}]</name>
+      <name name="info" arity="0"/>
       <fsummary>Information about global groups</fsummary>
-      <type>
-        <v>Item, Info -- see below</v>
-      </type>
+      <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>
         <taglist>
-          <tag><c>{state, State}</c></tag>
+          <tag><c>{state, <anno>State</anno>}</c></tag>
           <item>
             <p>If the local node is part of a global group,
-              <c>State == synced</c>. If no global groups are defined,
-              <c>State == no_conf</c>.</p>
+              <c><anno>State</anno> == synced</c>. If no global groups are defined,
+              <c><anno>State</anno> == no_conf</c>.</p>
           </item>
-          <tag><c>{own_group_name, GroupName}</c></tag>
+          <tag><c>{own_group_name, <anno>GroupName</anno>}</c></tag>
           <item>
             <p>The name (atom) of the group that the local node belongs
               to.</p>
           </item>
-          <tag><c>{own_group_nodes, Nodes}</c></tag>
+          <tag><c>{own_group_nodes, <anno>Nodes</anno>}</c></tag>
           <item>
             <p>A list of node names (atoms), the group nodes.</p>
           </item>
-          <tag><c>{synced_nodes, Nodes}</c></tag>
+          <tag><c>{synced_nodes, <anno>Nodes</anno>}</c></tag>
           <item>
             <p>A list of node names, the group nodes currently
               synchronized with the local node.</p>
           </item>
-          <tag><c>{sync_error, Nodes}</c></tag>
+          <tag><c>{sync_error, <anno>Nodes</anno>}</c></tag>
           <item>
             <p>A list of node names, the group nodes with which
               the local node has failed to synchronize.</p>
           </item>
-          <tag><c>{no_contact, Nodes}</c></tag>
+          <tag><c>{no_contact, <anno>Nodes</anno>}</c></tag>
           <item>
             <p>A list of node names, the group nodes to which there are
               currently no connections.</p>
           </item>
-          <tag><c>{other_groups, Groups}</c></tag>
+          <tag><c>{other_groups, <anno>Groups</anno>}</c></tag>
           <item>
-            <p><c>Groups</c> is a list of tuples
-              <c>{GroupName, Nodes}</c>, specifying the name and nodes
+            <p><c><anno>Groups</anno></c> is a list of tuples
+              <c>{<anno>GroupName</anno>, <anno>Nodes</anno>}</c>, specifying the name and nodes
               of the other global groups.</p>
           </item>
-          <tag><c>{monitoring, Pids}</c></tag>
+          <tag><c>{monitoring, <anno>Pids</anno>}</c></tag>
           <item>
             <p>A list of pids, specifying the processes which have
               subscribed to <c>nodeup</c> and <c>nodedown</c> messages.</p>
@@ -153,73 +163,52 @@
       </desc>
     </func>
     <func>
-      <name>monitor_nodes(Flag) -> ok </name>
+      <name name="monitor_nodes" arity="1"/>
       <fsummary>Subscribe to node status changes</fsummary>
-      <type>
-        <v>Flag = bool()</v>
-      </type>
       <desc>
-        <p>Depending on <c>Flag</c>, the calling process starts
-          subscribing (<c>Flag == true</c>) or stops subscribing
-          (<c>Flag == false</c>) to node status change messages.</p>
+        <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
           <c>{nodeup, Node}</c> and <c>{nodedown, Node}</c> when a
           group node connects or disconnects, respectively.</p>
       </desc>
     </func>
     <func>
-      <name>own_nodes() -> Nodes</name>
+      <name name="own_nodes" arity="0"/>
       <fsummary>Return the group nodes</fsummary>
-      <type>
-        <v>Nodes = [Node]</v>
-        <v>&nbsp;Node = node()</v>
-      </type>
       <desc>
         <p>Returns the names of all group nodes, regardless of their
           current status.</p>
       </desc>
     </func>
     <func>
-      <name>registered_names(Where) -> Names</name>
+      <name name="registered_names" arity="1"/>
       <fsummary>Return globally registered names</fsummary>
-      <type>
-        <v>Where = {node, Node} | {group, GroupName}</v>
-        <v>&nbsp;Node = node()</v>
-        <v>&nbsp;GroupName = atom()</v>
-        <v>Names = [Name]</v>
-        <v>&nbsp;Name = atom()</v>
-      </type>
       <desc>
         <p>Returns a list of all names which are globally registered
           on the specified node or in the specified global group.</p>
       </desc>
     </func>
     <func>
-      <name>send(Name, Msg) -> pid() | {badarg, {Name, Msg}}</name>
-      <name>send(Where, Name, Msg) -> pid() | {badarg, {Name, Msg}}</name>
+      <name name="send" arity="2"/>
+      <name name="send" arity="3"/>
       <fsummary>Send a message to a globally registered pid</fsummary>
-      <type>
-        <v>Where = {node, Node} | {group, GroupName}</v>
-        <v>&nbsp;Node = node()</v>
-        <v>&nbsp;GroupName = atom()</v>
-        <v>Name = atom()</v>
-        <v>Msg = term()</v>
-      </type>
       <desc>
-        <p>Searches for <c>Name</c>, globally registered on
+        <p>Searches for <c><anno>Name</anno></c>, globally registered on
           the specified node or in the specified global group, or --
-          if the <c>Where</c> argument is not provided -- in any global
+          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>Name</c> is found, the message <c>Msg</c> is sent to
+        <p>If <c><anno>Name</anno></c> is found, the 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, {Name, Msg}}</c>.</p>
+          <c>{badarg, {<anno>Name</anno>, <anno>Msg</anno>}}</c>.</p>
       </desc>
     </func>
     <func>
-      <name>sync() -> ok</name>
+      <name name="sync" arity="0"/>
       <fsummary>Synchronize the group nodes</fsummary>
       <desc>
         <p>Synchronizes the group nodes, that is, the global name
@@ -235,23 +224,17 @@
       </desc>
     </func>
     <func>
-      <name>whereis_name(Name) -> pid() | undefined</name>
-      <name>whereis_name(Where, Name) -> pid() | undefined</name>
+      <name name="whereis_name" arity="1"/>
+      <name name="whereis_name" arity="2"/>
       <fsummary>Get the pid with a given globally registered name</fsummary>
-      <type>
-        <v>Where = {node, Node} | {group, GroupName}</v>
-        <v>&nbsp;Node = node()</v>
-        <v>&nbsp;GroupName = atom()</v>
-        <v>Name = atom()</v>
-      </type>
       <desc>
-        <p>Searches for <c>Name</c>, globally registered on
+        <p>Searches for <c><anno>Name</anno></c>, globally registered on
           the specified node or in the specified global group, or -- if
-          the <c>Where</c> argument is not provided -- in any global
+          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>Name</c> is found, the corresponding pid is returned.
+        <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>