Use Erlang specs and types for documentation

1 files changed, 69 insertions, 94 deletions

diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml
index aa171c77c2..f1d42d9faa 100644
--- a/lib/kernel/doc/src/gen_tcp.xml
+++ b/lib/kernel/doc/src/gen_tcp.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>
@@ -63,36 +63,45 @@ do_recv(Sock, Bs) ->
     <p>For more examples, see the <seealso marker="#examples">examples</seealso> section.</p>
   </description>
 
-  <section>
-    <title>DATA TYPES</title>
-    <code type="none">
-ip_address()
-  see inet(3)
-
-posix()
-  see inet(3)
+  <datatypes>
+    <datatype>
+      <name name="hostname"/>
+    </datatype>
+    <datatype>
+      <name name="ip_address"/>
+      <desc>
+        <p>Represents an address of a TCP socket.
+          It is a tuple as explained in
+          <seealso marker="inet">inet(3)</seealso>.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="port_number"/>
+    </datatype>
+    <datatype>
+      <name name="posix"/>
+      <desc>
+        <p>See <seealso marker="inet#error_codes">
+        inet(3); POSIX Error Codes</seealso>.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name><marker id="type-socket">socket()</marker></name>
+      <desc>
+        <p>As returned by accept/1,2 and connect/3,4.</p>
+        <marker id="connect"></marker>
+      </desc>
+    </datatype>
+  </datatypes>
 
-socket()
-  as returned by accept/1,2 and connect/3,4</code>
-    <marker id="connect"></marker>
-  </section>
   <funcs>
     <func>
-      <name>connect(Address, Port, Options) -> {ok, Socket} | {error, Reason}</name>
-      <name>connect(Address, Port, Options, Timeout) -> {ok, Socket} | {error, Reason}</name>
+      <name name="connect" arity="3"/>
+      <name name="connect" arity="4"/>
       <fsummary>Connect to a TCP port</fsummary>
-      <type>
-        <v>Address = string() | atom() | ip_address()</v>
-        <v>Port = 0..65535</v>
-        <v>Options = [Opt]</v>
-        <v>&nbsp;Opt -- see below</v>
-        <v>Timeout = int() | infinity</v>
-        <v>Socket = socket()</v>
-        <v>Reason = posix()</v>
-      </type>
       <desc>
-        <p>Connects to a server on TCP port <c>Port</c> on the host
-          with IP address <c>Address</c>. The <c>Address</c> argument
+        <p>Connects to a server on TCP port <c><anno>Port</anno></c> on the host
+          with IP address <c><anno>Address</anno></c>. The <c><anno>Address</anno></c> argument
           can be either a hostname, or an IP address.</p>
         <p>The available options are:</p>
         <taglist>
@@ -127,13 +136,13 @@ socket()
           <item>
             <p>Set up the socket for IPv4.</p>
           </item>
-          <tag>Opt</tag>
+          <tag><c>Opt</c></tag>
           <item>
             <p>See
               <seealso marker="inet#setopts/2">inet:setopts/2</seealso>.</p>
           </item>
         </taglist>
-        <p>Packets can be sent to the returned socket <c>Socket</c>
+        <p>Packets can be sent to the returned socket <c><anno>Socket</anno></c>
           using <c>send/2</c>. Packets sent from the peer are delivered
           as messages:</p>
         <code type="none">
@@ -148,7 +157,7 @@ socket()
         <p>unless <c>{active, false}</c> is specified in the option list
           for the socket, in which case packets are retrieved by
           calling <c>recv/2</c>.</p>
-        <p>The optional <c>Timeout</c> parameter specifies a timeout in
+        <p>The optional <c><anno>Timeout</anno></c> parameter specifies a timeout in
           milliseconds. The default value is <c>infinity</c>.</p>
         <note>
           <p>The default values for options given to <c>connect</c> can
@@ -159,19 +168,12 @@ socket()
       </desc>
     </func>
     <func>
-      <name>listen(Port, Options) -> {ok, ListenSocket} | {error, Reason}</name>
+      <name name="listen" arity="2"/>
       <fsummary>Set up a socket to listen on a port</fsummary>
-      <type>
-        <v>Port = 0..65535</v>
-        <v>Options = [Opt]</v>
-        <v>&nbsp;Opt -- see below</v>
-        <v>ListenSocket -- see below</v>
-        <v>Reason = posix()</v>
-      </type>
       <desc>
-        <p>Sets up a socket to listen on the port <c>Port</c> on
+        <p>Sets up a socket to listen on the port <c><anno>Port</anno></c> on
           the local host.</p>
-        <p>If <c>Port == 0</c>, the underlying OS assigns an available
+        <p>If <c><anno>Port</anno> == 0</c>, the underlying OS assigns an available
           port number, use <c>inet:port/1</c> to retrieve it.</p>
         <p>The available options are:</p>
         <taglist>
@@ -214,7 +216,7 @@ socket()
               <seealso marker="inet#setopts/2">inet:setopts/2</seealso>.</p>
           </item>
         </taglist>
-        <p>The returned socket <c>ListenSocket</c> can only be used in
+        <p>The returned socket <c><anno>ListenSocket</anno></c> can only be used in
           calls to <c>accept/1,2</c>.</p>
         <note>
           <p>The default values for options given to <c>listen</c> can
@@ -225,27 +227,23 @@ socket()
       </desc>
     </func>
     <func>
-      <name>accept(ListenSocket) -> {ok, Socket} | {error, Reason}</name>
-      <name>accept(ListenSocket, Timeout) -> {ok, Socket} | {error, Reason}</name>
+      <name name="accept" arity="1"/>
+      <name name="accept" arity="2"/>
       <fsummary>Accept an incoming connection request on a listen socket</fsummary>
-      <type>
-        <v>ListenSocket -- see listen/2</v>
-        <v>Timeout = int() | infinity</v>
-        <v>Socket = socket()</v>
-        <v>Reason = closed | timeout | posix()</v>
-      </type>
+      <type_desc variable="ListenSocket">Returned by <c>listen/2</c>.
+      </type_desc>
       <desc>
         <p>Accepts an incoming connection request on a listen socket.
-          <c>Socket</c> must be a socket returned from <c>listen/2</c>.
-          <c>Timeout</c> specifies a timeout value in ms, defaults to
+          <c><anno>Socket</anno></c> must be a socket returned from <c>listen/2</c>.
+          <c><anno>Timeout</anno></c> specifies a timeout value in ms, defaults to
           <c>infinity</c>.</p>
-        <p>Returns <c>{ok, Socket}</c> if a connection is established,
-          or <c>{error, closed}</c> if <c>ListenSocket</c> is closed,
+        <p>Returns <c>{ok, <anno>Socket</anno>}</c> if a connection is established,
+          or <c>{error, closed}</c> if <c><anno>ListenSocket</anno></c> is closed,
           or <c>{error, timeout}</c> if no connection is established
           within the specified time. May also return a POSIX error
           value if something else goes wrong, see inet(3) for possible
           error values.</p>
-        <p>Packets can be sent to the returned socket <c>Socket</c>
+        <p>Packets can be sent to the returned socket <c><anno>Socket</anno></c>
           using <c>send/2</c>. Packets sent from the peer are delivered
           as messages:</p>
         <code type="none">
@@ -264,13 +262,8 @@ socket()
       </desc>
     </func>
     <func>
-      <name>send(Socket, Packet) -> ok | {error, Reason}</name>
+      <name name="send" arity="2"/>
       <fsummary>Send a packet</fsummary>
-      <type>
-        <v>Socket = socket()</v>
-        <v>Packet = [char()] | binary()</v>
-        <v>Reason = posix()</v>
-      </type>
       <desc>
         <p>Sends a packet on a socket. </p>
         <p>There is no <c>send</c> call with timeout option, you use the
@@ -279,70 +272,52 @@ socket()
       </desc>
     </func>
     <func>
-      <name>recv(Socket, Length) -> {ok, Packet} | {error, Reason}</name>
-      <name>recv(Socket, Length, Timeout) -> {ok, Packet} | {error, Reason}</name>
+      <name name="recv" arity="2"/>
+      <name name="recv" arity="3"/>
       <fsummary>Receive a packet from a passive socket</fsummary>
-      <type>
-        <v>Socket = socket()</v>
-        <v>Length  = int()</v>
-        <v>Packet = [char()] | binary() | HttpPacket</v>
-        <v>Timeout = int() | infinity</v>
-        <v>Reason = closed | posix()</v>
-        <v>HttpPacket = see the description of <c>HttpPacket</c> in <seealso marker="erts:erlang#decode_packet/3">erlang:decode_packet/3</seealso></v>
-      </type>
+      <type_desc variable="HttpPacket">See the description of
+         <c>HttpPacket</c> in <seealso marker="erts:erlang#decode_packet/3">
+         erlang:decode_packet/3</seealso>.
+      </type_desc>
       <desc>
         <p>This function receives a packet from a socket in passive
           mode. A closed socket is indicated by a return value
           <c>{error, closed}</c>.</p>
-        <p>The <c>Length</c> argument is only meaningful when
+        <p>The <c><anno>Length</anno></c> argument is only meaningful when
           the socket is in <c>raw</c> mode and denotes the number of
-          bytes to read. If <c>Length</c> = 0, all available bytes are
-          returned. If <c>Length</c> &gt; 0, exactly <c>Length</c>
+          bytes to read. If <c><anno>Length</anno></c> = 0, all available bytes are
+          returned. If <c><anno>Length</anno></c> &gt; 0, exactly <c><anno>Length</anno></c>
           bytes are returned, or an error; possibly discarding less
-          than <c>Length</c> bytes of data when the socket gets closed
+          than <c><anno>Length</anno></c> bytes of data when the socket gets closed
           from the other side.</p>
-        <p>The optional <c>Timeout</c> parameter specifies a timeout in
+        <p>The optional <c><anno>Timeout</anno></c> parameter specifies a timeout in
           milliseconds. The default value is <c>infinity</c>.</p>
       </desc>
     </func>
     <func>
-      <name>controlling_process(Socket, Pid) -> ok | {error, Reason}</name>
+      <name name="controlling_process" arity="2"/>
       <fsummary>Change controlling process of a socket</fsummary>
-      <type>
-        <v>Socket = socket()</v>
-        <v>Pid = pid()</v>
-        <v>Reason = closed | not_owner | posix()</v>
-      </type>
       <desc>
-        <p>Assigns a new controlling process <c>Pid</c> to
-          <c>Socket</c>. The controlling process is the process which
+        <p>Assigns a new controlling process <c><anno>Pid</anno></c> to
+          <c><anno>Socket</anno></c>. The controlling process is the process which
           receives messages from the socket. If called by any other
           process than the current controlling process,
           <c>{error, eperm}</c> is returned.</p>
       </desc>
     </func>
     <func>
-      <name>close(Socket) -> ok | {error, Reason}</name>
+      <name name="close" arity="1"/>
       <fsummary>Close a TCP socket</fsummary>
-      <type>
-        <v>Socket = socket()</v>
-        <v>Reason = posix()</v>
-      </type>
       <desc>
         <p>Closes a TCP socket.</p>
       </desc>
     </func>
     <func>
-      <name>shutdown(Socket, How) -> ok | {error, Reason}</name>
+      <name name="shutdown" arity="2"/>
       <fsummary>Immediately close a socket</fsummary>
-      <type>
-        <v>Socket = socket()</v>
-        <v>How = read | write | read_write</v>
-        <v>Reason = posix()</v>
-      </type>
       <desc>
         <p>Immediately close a socket in one or two directions.</p>
-        <p><c>How == write</c> means closing the socket for writing,
+        <p><c><anno>How</anno> == write</c> means closing the socket for writing,
           reading from it is still possible.</p>
         <p>To be able to handle that the peer has done a shutdown on
           the write side, the <c>{exit_on_close, false}</c> option