Use Erlang specs and types for documentation

1 files changed, 44 insertions, 57 deletions

diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml
index 71f2e9bd83..c0e783f508 100644
--- a/lib/kernel/doc/src/gen_udp.xml
+++ b/lib/kernel/doc/src/gen_udp.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1997</year><year>2009</year>
+      <year>1997</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -34,32 +34,43 @@
       with sockets using the UDP protocol.</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 open/1,2.</p>
+      </desc>
+    </datatype>
+  </datatypes>
 
-socket()
-  as returned by open/1,2</code>
-  </section>
   <funcs>
     <func>
-      <name>open(Port) -> {ok, Socket} | {error, Reason}</name>
-      <name>open(Port, Options) -> {ok, Socket} | {error, Reason}</name>
+      <name name="open" arity="1"/>
+      <name name="open" arity="2"/>
       <fsummary>Associate a UDP port number with the process calling it</fsummary>
-      <type>
-        <v>Port = 0..65535</v>
-        <v>Options = [Opt]</v>
-        <v>&nbsp;Opt -- see below</v>
-        <v>Socket = socket()</v>
-        <v>Reason = posix()</v>
-      </type>
       <desc>
-        <p>Associates a UDP port number (<c>Port</c>) with the calling
+        <p>Associates a UDP port number (<c><anno>Port</anno></c>) with the calling
           process.</p>
         <p>The available options are:</p>
         <taglist>
@@ -96,7 +107,7 @@ socket()
               <seealso marker="inet#setopts/2">inet:setopts/2</seealso>.</p>
           </item>
         </taglist>
-        <p>The returned socket <c>Socket</c> is used to send packets
+        <p>The returned socket <c><anno>Socket</anno></c> is used to send packets
           from this port with <c>send/4</c>. When UDP packets arrive at
           the opened port, they are delivered as messages:</p>
         <code type="none">
@@ -110,66 +121,42 @@ socket()
           binary if the option <c>binary</c> was specified.</p>
         <p>Default value for the receive buffer option is
           <c>{recbuf, 8192}</c>.</p>
-        <p>If <c>Port == 0</c>, the underlying OS assigns a free UDP
+        <p>If <c><anno>Port</anno> == 0</c>, the underlying OS assigns a free UDP
           port, use <c>inet:port/1</c> to retrieve it.</p>
       </desc>
     </func>
     <func>
-      <name>send(Socket, Address, Port, Packet) -> ok | {error, Reason}</name>
+      <name name="send" arity="4"/>
       <fsummary>Send a packet</fsummary>
-      <type>
-        <v>Socket = socket()</v>
-        <v>Address = string() | atom() | ip_address()</v>
-        <v>Port = 0..65535</v>
-        <v>Packet = [char()] | binary()</v>
-        <v>Reason = not_owner | posix()</v>
-      </type>
       <desc>
         <p>Sends a packet to the specified address and port.
-          The <c>Address</c> argument can be either a hostname, or an
+          The <c><anno>Address</anno></c> argument can be either a hostname, or an
           IP address.</p>
       </desc>
     </func>
     <func>
-      <name>recv(Socket, Length) -> {ok, {Address, Port, Packet}} | {error, Reason}</name>
-      <name>recv(Socket, Length, Timeout) -> {ok, {Address, Port, 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>Address = ip_address()</v>
-        <v>Port = 0..65535</v>
-        <v>Packet = [char()] | binary()</v>
-        <v>Timeout = int() | infinity</v>
-        <v>Reason = not_owner | posix()</v>
-      </type>
       <desc>
         <p>This function receives a packet from a socket in passive
           mode.</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</name>
+      <name name="controlling_process" arity="2"/>
       <fsummary>Change controlling process of a socket</fsummary>
-      <type>
-        <v>Socket = socket()</v>
-        <v>Pid = pid()</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.</p>
       </desc>
     </func>
     <func>
-      <name>close(Socket) -> ok | {error, Reason}</name>
+      <name name="close" arity="1"/>
       <fsummary>Close a UDP socket</fsummary>
-      <type>
-        <v>Socket = socket()</v>
-        <v>Reason = not_owner | posix()</v>
-      </type>
       <desc>
         <p>Closes a UDP socket.</p>
       </desc>