Merge branch 'hb/kernel/doc_specs/OTP-9272' into dev

* hb/kernel/doc_specs/OTP-9272:
  Use Erlang specs and types for documentation

1 files changed, 23 insertions, 51 deletions

diff --git a/lib/kernel/doc/src/net_adm.xml b/lib/kernel/doc/src/net_adm.xml
index 7ec4f7f0e7..f2aac9282c 100644
--- a/lib/kernel/doc/src/net_adm.xml
+++ b/lib/kernel/doc/src/net_adm.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2009</year>
+      <year>1996</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -34,94 +34,70 @@
   </description>
   <funcs>
     <func>
-      <name>dns_hostname(Host) -> {ok, Name} | {error, Host}</name>
+      <name name="dns_hostname" arity="1"/>
       <fsummary>Official name of a host</fsummary>
-      <type>
-        <v>Host = atom() | string()</v>
-        <v>Name = string()</v>
-      </type>
       <desc>
-        <p>Returns the official name of <c>Host</c>, or
-          <c>{error, Host}</c> if no such name is found. See also
+        <p>Returns the official name of <c><anno>Host</anno></c>, or
+          <c>{error, <anno>Host</anno>}</c> if no such name is found. See also
           <c>inet(3)</c>.</p>
       </desc>
     </func>
     <func>
-      <name>host_file() -> Hosts | {error, Reason}</name>
+      <name name="host_file" arity="0"/>
       <fsummary>Read the <c>.hosts.erlang</c>file</fsummary>
-      <type>
-        <v>Hosts = [Host]</v>
-        <v>&nbsp;Host = atom()</v>
-        <v>Reason = term()</v>
-      </type>
       <desc>
         <p>Reads the <c>.hosts.erlang</c> file, see the section
           <em>Files</em> below. Returns the hosts in this file as a
-          list, or returns <c>{error, Reason}</c> if the file could not
-          be read. See <c>file(3)</c> for possible values of
-          <c>Reason</c>.</p>
+          list, or returns <c>{error, <anno>Reason</anno>}</c> if the file could not
+          be read or the Erlang terms on the file could not be interpreted.</p>
       </desc>
     </func>
     <func>
-      <name>localhost() -> Name</name>
+      <name name="localhost" arity="0"/>
       <fsummary>Name of the local host</fsummary>
-      <type>
-        <v>Name = string()</v>
-      </type>
       <desc>
         <p>Returns the name of the local host. If Erlang was started
-          with the <c>-name</c> command line flag, <c>Name</c> is
+          with the <c>-name</c> command line flag, <c><anno>Name</anno></c> is
           the fully qualified name.</p>
       </desc>
     </func>
     <func>
-      <name>names() -> {ok, [{Name, Port}]} | {error, Reason}</name>
-      <name>names(Host) -> {ok, [{Name, Port}]} | {error, Reason}</name>
+      <name name="names" arity="0"/>
+      <name name="names" arity="1"/>
       <fsummary>Names of Erlang nodes at a host</fsummary>
-      <type>
-        <v>Name = string()</v>
-        <v>Port = int()</v>
-        <v>Reason = address | term()</v>
-      </type>
       <desc>
         <p>Similar to <c>epmd -names</c>, see <c>epmd(1)</c>.
-          <c>Host</c> defaults to the local host. Returns the names and
+          <c><anno>Host</anno></c> defaults to the local host. Returns the names and
           associated port numbers of the Erlang nodes that <c>epmd</c>
           at the specified host has registered.</p>
         <p>Returns <c>{error, address}</c> if <c>epmd</c> is not
-          running. See <c>inet(3)</c> for other possible values of
-          <c>Reason</c>.</p>
+          running.</p>
         <pre>
 (arne@dunn)1> <input>net_adm:names().</input>
 {ok,[{"arne",40262}]}</pre>
       </desc>
     </func>
     <func>
-      <name>ping(Node) -> pong | pang</name>
+      <name name="ping" arity="1"/>
       <fsummary>Set up a connection to a node</fsummary>
-      <type>
-        <v>Node = node()</v>
-      </type>
       <desc>
-        <p>Tries to set up a connection to <c>Node</c>. Returns
+        <p>Tries to set up a connection to <c><anno>Node</anno></c>. Returns
           <c>pang</c> if it fails, or <c>pong</c> if it is successful.</p>
       </desc>
     </func>
     <func>
-      <name>world() -> [node()]</name>
-      <name>world(Arg) -> [node()]</name>
+      <name name="world" arity="0"/>
+      <name name="world" arity="1"/>
+      <type name="verbosity"/>
       <fsummary>Lookup and connect to all nodes at all hosts in <c>.hosts.erlang</c></fsummary>
-      <type>
-        <v>Arg = silent | verbose</v>
-      </type>
       <desc>
         <p>This function calls <c>names(Host)</c> for all hosts which
           are specified in the Erlang host file <c>.hosts.erlang</c>,
           collects the replies and then evaluates <c>ping(Node)</c> on
           all those nodes. Returns the list of all nodes that were,
 	  successfully pinged.</p>
-        <p><c>Arg</c> defaults to <c>silent</c>.
-	 If <c>Arg == verbose</c>, the function writes information about which
+        <p><c><anno>Arg</anno></c> defaults to <c>silent</c>.
+	 If <c><anno>Arg</anno> == verbose</c>, the function writes information about which
           nodes it is pinging to stdout.</p>
         <p>This function can be useful when a node is started, and
           the names of the other nodes in the network are not initially
@@ -131,14 +107,10 @@
       </desc>
     </func>
     <func>
-      <name>world_list(Hosts) -> [node()]</name>
-      <name>world_list(Hosts, Arg) -> [node()]</name>
+      <name name="world_list" arity="1"/>
+      <name name="world_list" arity="2"/>
+      <type name="verbosity"/>
       <fsummary>Lookup and connect to all nodes at specified hosts</fsummary>
-      <type>
-        <v>Hosts = [Host]</v>
-        <v>&nbsp;Host = atom()</v>
-        <v>Arg = silent | verbose</v>
-      </type>
       <desc>
         <p>As <c>world/0,1</c>, but the hosts are given as argument
           instead of being read from <c>.hosts.erlang</c>.</p>