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, 75 insertions, 118 deletions

diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml
index f05a224f33..fd843b00d9 100644
--- a/lib/kernel/doc/src/inet.xml
+++ b/lib/kernel/doc/src/inet.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1997</year><year>2010</year>
+      <year>1997</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -54,33 +54,6 @@ $ <input>erl -sname test -kernel \</input>
 <input>inet_default_listen_options '[{delay_send,true}]'</input></pre>
     <p>Note that the default option <c>{active, true}</c> currently
       cannot be changed, for internal reasons.</p>
-  </description>
-
-  <section>
-    <title>DATA TYPES</title>
-    <code type="none">
-#hostent{h_addr_list = [ip_address()]  % list of addresses for this host
-         h_addrtype  = inet | inet6
-         h_aliases = [hostname()]      % list of aliases
-         h_length = int()              % length of address in bytes
-         h_name = hostname()           % official name for host
-  The record is defined in the Kernel include file "inet.hrl"
-  Add the following directive to the module:
-    -include_lib("kernel/include/inet.hrl").
-
-hostname() = atom() | string()
-
-ip_address() = {N1,N2,N3,N4}              % IPv4
-             | {K1,K2,K3,K4,K5,K6,K7,K8}  % IPv6
-  Ni = 0..255
-  Ki = 0..65535
-
-posix()
-  an atom which is named from the Posix error codes used in
-  Unix, and in the runtime libraries of most C compilers
-
-socket()
-  see gen_tcp(3), gen_udp(3)</code>
     <p>Addresses as inputs to functions can be either a string or a
       tuple. For instance, the IP address 150.236.20.73 can be passed to
       <c>gethostbyaddr/1</c> either as the string "150.236.20.73"
@@ -109,24 +82,58 @@ fe80::204:acff:fe17:bf38
 {ok,{192,168,42,2}}
 2> <input>inet_parse:address("FFFF::192.168.42.2").</input>
 {ok,{65535,0,0,0,0,0,49320,10754}}</pre>
-  </section>
+  </description>
+
+  <datatypes>
+    <datatype>
+      <name name="hostent"/>
+      <desc>
+        <p>The record is defined in the Kernel include file "inet.hrl".
+          Add the following directive to the module:</p>
+<code>-include_lib("kernel/include/inet.hrl").</code></desc>
+    </datatype>
+    <datatype>
+      <name name="hostname"/>
+    </datatype>
+    <datatype>
+      <name name="ip_address"/>
+    </datatype>
+    <datatype>
+      <name name="ip4_address"/>
+    </datatype>
+    <datatype>
+      <name name="ip6_address"/>
+    </datatype>
+    <datatype>
+      <name name="posix"/>
+      <desc><p>An atom which is named from the Posix error codes
+         used in Unix, and in the runtime libraries of most
+          C compilers. See
+          <seealso marker="#error_codes">POSIX Error Codes</seealso>.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name><marker id="type-socket">socket()</marker></name>
+      <desc><p>See <seealso marker="gen_tcp#type-socket">gen_tcp(3)</seealso>
+         and <seealso marker="gen_udp#type-socket">gen_udp(3)</seealso>.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="family_option"/>
+    </datatype>
+  </datatypes>
+
   <funcs>
     <func>
-      <name>close(Socket) -> ok</name>
+      <name name="close" arity="1"/>
       <fsummary>Close a socket of any type</fsummary>
-      <type>
-        <v>Socket = socket()</v>
-      </type>
       <desc>
         <p>Closes a socket of any type.</p>
       </desc>
     </func>
     <func>
-      <name>get_rc() -> [{Par, Val}]</name>
+      <name name="get_rc" arity="0"/>
       <fsummary>Return a list of IP configuration parameters</fsummary>
-      <type>
-        <v>Par, Val -- see below</v>
-      </type>
       <desc>
         <p>Returns the state of the Inet configuration database in 
           form of a list of recorded configuration parameters. (See the
@@ -135,116 +142,74 @@ fe80::204:acff:fe17:bf38
       </desc>
     </func>
     <func>
-      <name>format_error(Posix) -> string()</name>
+      <name name="format_error" arity="1"/>
       <fsummary>Return a descriptive string for an error reason</fsummary>
-      <type>
-        <v>Posix = posix()</v>
-      </type>
       <desc>
         <p>Returns a diagnostic error string. See the section below
-          for possible <c>Posix</c> values and the corresponding
+          for possible <c><anno>Posix</anno></c> values and the corresponding
           strings.</p>
       </desc>
     </func>
     <func>
-      <name>getaddr(Host, Family) -> {ok, Address} | {error, posix()}</name>
+      <name name="getaddr" arity="2"/>
       <fsummary>Return the IP-address for a host</fsummary>
-      <type>
-        <v>Host = ip_address() | string() | atom()</v>
-        <v>Family = inet | inet6</v>
-        <v>Address = ip_address()</v>
-        <v>posix() = term()</v>
-      </type>
       <desc>
-        <p>Returns the IP-address for <c>Host</c> as a tuple of
-          integers. <c>Host</c> can be an IP-address, a single hostname
+        <p>Returns the IP-address for <c><anno>Host</anno></c> as a tuple of
+          integers. <c><anno>Host</anno></c> can be an IP-address, a single hostname
           or a fully qualified hostname.</p>
       </desc>
     </func>
     <func>
-      <name>getaddrs(Host, Family) -> {ok, Addresses} | {error, posix()}</name>
+      <name name="getaddrs" arity="2"/>
       <fsummary>Return the IP-addresses for a host</fsummary>
-      <type>
-        <v>Host = ip_address() | string() | atom()</v>
-        <v>Addresses = [ip_address()]</v>
-        <v>Family = inet | inet6</v>
-      </type>
       <desc>
-        <p>Returns a list of all IP-addresses for <c>Host</c>.
-          <c>Host</c> can be an IP-address, a single hostname or a fully
+        <p>Returns a list of all IP-addresses for <c><anno>Host</anno></c>.
+          <c><anno>Host</anno></c> can be an IP-address, a single hostname or a fully
           qualified hostname.</p>
       </desc>
     </func>
     <func>
-      <name>gethostbyaddr(Address) -> {ok, Hostent} | {error, posix()}</name>
+      <name name="gethostbyaddr" arity="1"/>
       <fsummary>Return a hostent record for the host with the given address</fsummary>
-      <type>
-        <v>Address = string() | ip_address()</v>
-        <v>Hostent = #hostent{}</v>
-      </type>
       <desc>
         <p>Returns a <c>hostent</c> record given an address.</p>
       </desc>
     </func>
     <func>
-      <name>gethostbyname(Name) -> {ok, Hostent} | {error, posix()}</name>
+      <name name="gethostbyname" arity="1"/>
       <fsummary>Return a hostent record for the host with the given name</fsummary>
-      <type>
-        <v>Hostname = hostname()</v>
-        <v>Hostent = #hostent{}</v>
-      </type>
       <desc>
         <p>Returns a <c>hostent</c> record given a hostname.</p>
       </desc>
     </func>
     <func>
-      <name>gethostbyname(Name, Family) -> {ok, Hostent} | {error, posix()}</name>
+      <name name="gethostbyname" arity="2"/>
       <fsummary>Return a hostent record for the host with the given name</fsummary>
-      <type>
-        <v>Hostname = hostname()</v>
-        <v>Family = inet | inet6</v>
-        <v>Hostent = #hostent{}</v>
-      </type>
       <desc>
         <p>Returns a <c>hostent</c> record given a hostname, restricted
           to the given address family.</p>
       </desc>
     </func>
     <func>
-      <name>gethostname() -> {ok, Hostname}</name>
+      <name name="gethostname" arity="0"/>
       <fsummary>Return the local hostname</fsummary>
-      <type>
-        <v>Hostname = string()</v>
-      </type>
       <desc>
         <p>Returns the local hostname. Will never fail.</p>
       </desc>
     </func>
 
     <func>
-      <name>getifaddrs() -> {ok,Iflist} | {error,posix}</name>
+      <name name="getifaddrs" arity="0"/>
       <fsummary>Return a list of interfaces and their addresses</fsummary>
-      <type>
-	<v>Iflist = {Ifname,[Ifopt]}</v>
-	<v>Ifname = string()</v>
-	<v>Ifopt = {flag,[Flag]} | {addr,Addr} | {netmask,Netmask}
-	           | {broadaddr,Broadaddr} | {dstaddr,Dstaddr}
-	           | {hwaddr,Hwaddr}</v>
-	<v>Flag = up | broadcast | loopback | pointtopoint
-	          | running | multicast</v>
-	<v>Addr = Netmask = Broadadddr = Dstaddr = ip_address()</v>
-	<v>Hwaddr = [byte()]</v>
-      </type>
-    </func>
     <desc>
       <p>
 	Returns a list of 2-tuples containing interface names and the
-	interface's addresses. <c>Ifname</c> is a Unicode string.
-	<c>Hwaddr</c> is hardware dependent, e.g on Ethernet interfaces
+	interface's addresses. <c><anno>Ifname</anno></c> is a Unicode string.
+	<c><anno>Hwaddr</anno></c> is hardware dependent, e.g on Ethernet interfaces
 	it is the 6-byte Ethernet address (MAC address (EUI-48 address)).
       </p>
       <p>
-	The <c>{addr,Addr}</c>, <c>{netmask,_}</c> and <c>{broadaddr,_}</c>
+	The <c>{addr,<anno>Addr</anno>}</c>, <c>{netmask,_}</c> and <c>{broadaddr,_}</c>
 	tuples are repeated in the result list iff the interface has multiple
 	addresses. If you come across an interface that has
 	multiple <c>{flag,_}</c> or <c>{hwaddr,_}</c> tuples you have
@@ -252,8 +217,8 @@ fe80::204:acff:fe17:bf38
 	The <c>{flag,_}</c> tuple is mandatory, all other optional.
       </p>
       <p>
-	Do not rely too much on the order of <c>Flag</c> atoms or
-	<c>Ifopt</c> tuples. There are some rules, though:
+	Do not rely too much on the order of <c><anno>Flag</anno></c> atoms or
+	<c><anno>Ifopt</anno></c> tuples. There are some rules, though:
 	<list>
 	  <item>
 	    Immediately after <c>{addr,_}</c> follows <c>{netmask,_}</c>
@@ -261,7 +226,7 @@ fe80::204:acff:fe17:bf38
 	  <item>
 	    Immediately thereafter follows <c>{broadaddr,_}</c> if
 	    the <c>broadcast</c> flag is <em>not</em> set and the
-	    <c>pointtopoint</c>flag <em>is</em> set.
+	    <c>pointtopoint</c> flag <em>is</em> set.
 	  </item>
 	  <item>
 	    Any <c>{netmask,_}</c>, <c>{broadaddr,_}</c> or
@@ -277,11 +242,12 @@ fe80::204:acff:fe17:bf38
       </p>
       <p>
 	On Windows, the data is fetched from quite different OS API
-	functions, so the <c>Netmask</c> and <c>Broadaddr</c>
-	values may be calculated, just as some <c>Flag</c> values.
+	functions, so the <c><anno>Netmask</anno></c> and <c><anno>Broadaddr</anno></c>
+	values may be calculated, just as some <c><anno>Flag</anno></c> values.
 	You have been warned. Report flagrant bugs.
       </p>
     </desc>
+    </func>
 
     <func>
       <name>getopts(Socket, Options) -> {ok, OptionValues} | {error, posix()}</name>
@@ -291,13 +257,14 @@ fe80::204:acff:fe17:bf38
         <v>Options = [Opt | RawOptReq]</v>
         <v>Opt = atom()</v>
         <v>RawOptReq = {raw, Protocol, OptionNum, ValueSpec}</v>
-        <v>Protocol = int()</v>
-        <v>OptionNum = int()</v>
+        <v>Protocol = integer()</v>
+        <v>OptionNum = integer()</v>
         <v>ValueSpec = ValueSize | ValueBin</v>
-        <v>ValueSize = int()</v>
+        <v>ValueSize = integer()</v>
         <v>ValueBin = binary()</v>
         <v>OptionValues = [{Opt, Val} | {raw, Protocol, OptionNum,  ValueBin}]</v>
       </type>
+      <type name="socket_getopt"/>
       <desc>
         <p>Gets one or more options for a socket. 
           See <seealso marker="#setopts/2">setopts/2</seealso> 
@@ -419,13 +386,8 @@ fe80::204:acff:fe17:bf38
     </func>
 
     <func>
-      <name>peername(Socket) -> {ok, {Address, Port}} | {error, posix()}</name>
+      <name name="peername" arity="1"/>
       <fsummary>Return the address and port for the other end of a connection</fsummary>
-      <type>
-        <v>Socket = socket()</v>
-        <v>Address = ip_address()</v>
-        <v>Port = int()</v>
-      </type>
       <desc>
         <p>Returns the address and port for the other end of a
           connection.</p>
@@ -436,20 +398,15 @@ fe80::204:acff:fe17:bf38
       <fsummary>Return the local port number for a socket</fsummary>
       <type>
         <v>Socket = socket()</v>
-        <v>Port = int()</v>
+        <v>Port = integer()</v>
       </type>
       <desc>
         <p>Returns the local port number for a socket.</p>
       </desc>
     </func>
     <func>
-      <name>sockname(Socket) -> {ok, {Address, Port}} | {error, posix()}</name>
+      <name name="sockname" arity="1"/>
       <fsummary>Return the local address and port number for a socket</fsummary>
-      <type>
-        <v>Socket = socket()</v>
-        <v>Address = ip_address()</v>
-        <v>Port = int()</v>
-      </type>
       <desc>
         <p>Returns the local address and port number for a socket.</p>
       </desc>
@@ -460,8 +417,8 @@ fe80::204:acff:fe17:bf38
       <type>
         <v>Socket = term()</v>
         <v>Options = [{Opt, Val} | {raw, Protocol, Option, ValueBin}]</v>
-        <v>Protocol = int()</v>
-        <v>OptionNum = int()</v>
+        <v>Protocol = integer()</v>
+        <v>OptionNum = integer()</v>
         <v>ValueBin = binary()</v>
         <v>&nbsp;Opt, Val -- see below</v>
       </type>