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, 90 insertions, 147 deletions

diff --git a/lib/kernel/doc/src/gen_sctp.xml b/lib/kernel/doc/src/gen_sctp.xml
index fb09092f1c..5ceb82ae41 100644
--- a/lib/kernel/doc/src/gen_sctp.xml
+++ b/lib/kernel/doc/src/gen_sctp.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2007</year><year>2010</year>
+      <year>2007</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -65,77 +65,71 @@
       <item><seealso marker="#seealso">SEE ALSO</seealso></item>
       <item><seealso marker="#authors">AUTHORS</seealso></item>
     </list>
+    <marker id="types"></marker>
   </section>
 
-  <section>
-    <marker id="types"></marker>
-    <title>DATA TYPES</title>
-    <marker id="type-assoc_id"></marker>
-    <taglist>
-      <tag><c>assoc_id()</c></tag>
-      <item>
+  <datatypes>
+    <datatype>
+      <name name="assoc_id"/>
+      <desc>
         <p>An opaque term returned in for example #sctp_paddr_change{}
           that identifies an association for an SCTP socket. The term
           is opaque except for the special value <c>0</c> that has a
-          meaning such as "the whole endpoint" or "all future associations".</p>
-        <marker id="type-charlist"></marker>
-      </item>
-      <tag><c>charlist() = [char()]</c></tag>
-      <item>      <marker id="type-iolist"></marker>
-</item>
-      <tag><c>iolist() = [char() | binary()]</c></tag>
-      <item>      <marker id="type-ip_address"></marker>
-</item>
-      <tag><c>ip_address()</c></tag>
-      <item>
+          meaning such as "the whole endpoint" or "all future associations".
+        </p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="hostname"/>
+    </datatype>
+    <datatype>
+      <name name="ip_address"/>
+      <desc>
         <p>Represents an address of an SCTP socket. 
           It is a tuple as explained in
           <seealso marker="inet">inet(3)</seealso>.</p>
-        <marker id="type-port_number"></marker>
-      </item>
-      <tag><c>port_number() = 0 .. 65535</c></tag>
-      <item>      <marker id="type-posix"></marker>
-</item>
-      <tag><c>posix()</c></tag>
-      <item>
-        <p>See 
-          <seealso marker="inet#error_codes">inet(3); POSIX Error Codes.</seealso></p>
-        <marker id="type-sctp_option"></marker>
-      </item>
-      <tag><c>sctp_option()</c></tag>
-      <item>
+      </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 name="sctp_option"/>
+      <desc>
         <p>One of the 
           <seealso marker="#options">SCTP Socket Options.</seealso></p>
         <marker id="type-sctp_socket"></marker>
-      </item>
-      <tag><c>sctp_socket()</c></tag>
-      <item>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="sctp_socket"/>
+      <desc>
         <p>Socket identifier returned from <c>open/*</c>.</p>
-        <marker id="type-timeout"></marker>
-      </item>
-      <tag><c>timeout() = int() | infinity</c></tag>
-      <item>
-        <p>Timeout used in SCTP connect and receive calls.</p>
-      </item>
-    </taglist>
-    <marker id="exports"></marker>
-  </section>
+        <marker id="exports"></marker>
+      </desc>
+    </datatype>
+  </datatypes>
+
   <funcs>
     <func>
-      <name>abort(sctp_socket(), Assoc) -&gt; ok | {error, posix()}</name>
+      <name name="abort" arity="2"/>
       <fsummary>Abnormally terminate the association given by Assoc, without flushing of unsent data</fsummary>
-      <type>
-        <v>Assoc = #sctp_assoc_change{}</v>
-      </type>
       <desc>
-        <p>Abnormally terminates the association given by <c>Assoc</c>, without
+        <p>Abnormally terminates the association given by <c><anno>Assoc</anno></c>, without
           flushing of unsent data. The socket itself remains open. Other
           associations opened on this socket are still valid, and it can be
           used in new associations.</p>
       </desc>
     </func>
     <func>
-      <name>close(sctp_socket()) -&gt; ok | {error, posix()}</name>
+      <name name="close" arity="1"/>
       <fsummary>Completely close the socket and all associations on it</fsummary>
       <desc>
         <p>Completely closes the socket and all associations on it. The unsent
@@ -148,35 +142,26 @@
       </desc>
     </func>
     <func>
-      <name>connect(Socket, Addr, Port, Opts) -&gt; {ok,Assoc} | {error, posix()}</name>
+      <name name="connect" arity="4"/>
       <fsummary>Same as <c>connect(Socket, Addr, Port, Opts, infinity)</c>.</fsummary>
       <desc>
-        <p>Same as <c>connect(Socket, Addr, Port, Opts, infinity)</c>.</p>
+        <p>Same as <c>connect(<anno>Socket</anno>, <anno>Addr</anno>, <anno>Port</anno>, <anno>Opts</anno>, infinity)</c>.</p>
       </desc>
     </func>
     <func>
-      <name>connect(Socket, Addr, Port, [Opt], Timeout) -&gt; {ok, Assoc} | {error, posix()}</name>
+      <name name="connect" arity="5"/>
       <fsummary>Establish a new association for the socket <c>Socket</c>, with a peer (SCTP server socket)</fsummary>
-      <type>
-        <v>Socket  = sctp_socket()</v>
-        <v>Addr    = ip_address() | Host</v>
-        <v>Port    = port_number()</v>
-        <v>Opt     = sctp_option()</v>
-        <v>Timeout = timeout()</v>
-        <v>Host    = atom() | string()</v>
-        <v>Assoc   = #sctp_assoc_change{}</v>
-      </type>
       <desc>
-        <p>Establishes a new association for the socket <c>Socket</c>,
+        <p>Establishes a new association for the socket <c><anno>Socket</anno></c>,
           with the peer (SCTP server socket) given by
-          <c>Addr</c> and <c>Port</c>. The <c>Timeout</c>,
+          <c><anno>Addr</anno></c> and <c><anno>Port</anno></c>. The <c><anno>Timeout</anno></c>,
           is expressed in milliseconds. A socket can be associated with multiple peers.</p>
 
-        <p><b>WARNING:</b>Using a value of <c>Timeout</c> less than
+        <p><b>WARNING:</b>Using a value of <c><anno>Timeout</anno></c> less than
         the maximum time taken by the OS to establish an association (around 4.5 minutes
         if the default values from RFC 4960 are used) can result in
         inconsistent or incorrect return values. This is especially
-        relevant for associations sharing the same <c>Socket</c>
+        relevant for associations sharing the same <c><anno>Socket</anno></c>
         (i.e. source address and port) since the controlling process
         blocks until <c>connect/*</c> returns.
 	  <seealso marker="#connect_init/4">connect_init/*</seealso>
@@ -185,7 +170,7 @@
         <p><marker id="record-sctp_assoc_change"></marker>
           The result of <c>connect/*</c> is an <c>#sctp_assoc_change{}</c>
           event which contains, in particular, the new 
-          <seealso marker="#type-assoc_id">Association ID:</seealso></p>
+          <seealso marker="#type-assoc_id">Association ID</seealso>.</p>
         <pre>
   #sctp_assoc_change{
         state             = atom(),
@@ -198,13 +183,13 @@
           giving an <c>sctp_initmsg</c> option to <c>connect</c>
           as in:</p>
         <pre>
-  connect(Socket, Ip, Port,
+  connect(<anno>Socket</anno>, Ip, <anno>Port</anno>,
         [{sctp_initmsg,#sctp_initmsg{num_ostreams=OutStreams,
                                      max_instreams=MaxInStreams}}])        </pre>
-        <p>All options <c>Opt</c> are set on the socket before the 
+        <p>All options <c><anno>Opt</anno></c> are set on the socket before the
           association is attempted. If an option record has got undefined
           field values, the options record is first read from the socket
-          for those values. In effect, <c>Opt</c> option records only 
+          for those values. In effect, <c><anno>Opt</anno></c> option records only
           define field values to change before connecting.</p>
         <p>The returned <c>outbound_streams</c> and <c>inbound_streams</c>
           are the actual stream numbers on the socket, which may be different
@@ -242,27 +227,19 @@
       </desc>
     </func>
     <func>
-      <name>connect_init(Socket, Addr, Port, Opts) -&gt; ok | {error, posix()}</name>
+      <name name="connect_init" arity="4"/>
       <fsummary>Same as <c>connect_init(Socket, Addr, Port, Opts, infinity)</c>.</fsummary>
       <desc>
-        <p>Same as <c>connect_init(Socket, Addr, Port, Opts, infinity)</c>.</p>
+        <p>Same as <c>connect_init(<anno>Socket</anno>, <anno>Addr</anno>, <anno>Port</anno>, <anno>Opts</anno>, infinity)</c>.</p>
       </desc>
     </func>
     <func>
-      <name>connect_init(Socket, Addr, Port, [Opt], Timeout) -&gt; ok | {error, posix()}</name>
+      <name name="connect_init" arity="5"/>
       <fsummary>Initiate a new association for the socket <c>Socket</c>, with a peer (SCTP server socket)</fsummary>
-      <type>
-        <v>Socket  = sctp_socket()</v>
-        <v>Addr    = ip_address() | Host</v>
-        <v>Port    = port_number()</v>
-        <v>Opt     = sctp_option()</v>
-        <v>Timeout = timeout()</v>
-        <v>Host    = atom() | string()</v>
-      </type>
       <desc>
-        <p>Initiates a new association for the socket <c>Socket</c>,
+        <p>Initiates a new association for the socket <c><anno>Socket</anno></c>,
           with the peer (SCTP server socket) given by
-          <c>Addr</c> and <c>Port</c>.</p>
+          <c><anno>Addr</anno></c> and <c><anno>Port</anno></c>.</p>
 	<p>The fundamental difference between this API
 	and <c>connect/*</c> is that the return value is that of the
 	underlying OS connect(2) system call. If <c>ok</c> is returned
@@ -275,64 +252,52 @@
 	active option.</p>
 	<p>The parameters are as described
 	in <seealso marker="#connect/5">connect/*</seealso>, with the
-	exception of the <c>Timeout</c> value.</p>
-	<p>The timer associated with <c>Timeout</c> only supervises
-	IP resolution of <c>Addr</c></p>
+	exception of the <c><anno>Timeout</anno></c> value.</p>
+	<p>The timer associated with <c><anno>Timeout</anno></c> only supervises
+	IP resolution of <c><anno>Addr</anno></c></p>
       </desc>
     </func>
     <func>
-      <name>controlling_process(sctp_socket(), pid()) -&gt; ok</name>
+      <name name="controlling_process" arity="2"/>
       <fsummary>Assign a new controlling process pid to the socket</fsummary>
       <desc>
-        <p>Assigns a new controlling process Pid to Socket. Same implementation
+        <p>Assigns a new controlling process <c><anno>Pid</anno></c> to <c><anno>Socket</anno></c>. Same implementation
           as <c>gen_udp:controlling_process/2</c>.</p>
       </desc>
     </func>
     <func>
-      <name>eof(Socket, Assoc) -&gt; ok | {error, Reason}</name>
+      <name name="eof" arity="2"/>
       <fsummary>Gracefully terminate the association given by Assoc, with flushing of all unsent data</fsummary>
-      <type>
-        <v>Socket = sctp_socket()</v>
-        <v>Assoc  = #sctp_assoc_change{}</v>
-      </type>
       <desc>
-        <p>Gracefully terminates the association given by <c>Assoc</c>, with
+        <p>Gracefully terminates the association given by <c><anno>Assoc</anno></c>, with
           flushing of all unsent data. The socket itself remains open. Other
           associations opened on this socket are still valid, and it can be
           used in new associations.</p>
       </desc>
     </func>
     <func>
-      <name>listen(Socket, IsServer) -&gt; ok | {error, Reason}</name>
+      <name name="listen" arity="2"/>
       <fsummary>Set up a socket to listen.</fsummary>
-      <type>
-        <v>Socket   = sctp_socket()</v>
-        <v>IsServer = bool()</v>
-      </type>
       <desc>
         <p>Sets up a socket to listen on the IP address and port number
-          it is bound to. IsServer must be 'true' or 'false'.
+          it is bound to. <c><anno>IsServer</anno></c> must be <c>true</c>
+          or <c>false</c>.
           In the contrast to TCP, in SCTP there is no listening queue length.
-          If IsServer is 'true' the socket accepts new associations, i.e.
+          If <c><anno>IsServer</anno></c> is <c>true</c> the socket accepts new associations, i.e.
           it will become an SCTP server socket.</p>
       </desc>
     </func>
     <func>
-      <name>open() -&gt; {ok, Socket} | {error, posix()}</name>
-      <name>open(Port) -&gt; {ok, Socket} | {error, posix()}</name>
-      <name>open([Opt]) -&gt; {ok, Socket} | {error, posix()}</name>
-      <name>open(Port, [Opt]) -&gt; {ok, Socket} | {error, posix()}</name>
+      <name name="open" arity="0"/>
+      <name name="open" arity="1" clause_i="1"/>
+      <name name="open" arity="1" clause_i="2"/>
+      <name name="open" arity="2"/>
       <fsummary>Create an SCTP socket and bind it to local addresses</fsummary>
-      <type>
-        <v>Opt  = {ip,IP} | {ifaddr,IP} | {port,Port} | sctp_option()</v>
-        <v>IP   = ip_address() | any | loopback</v>
-        <v>Port = port_number()</v>
-      </type>
       <desc>
         <p>Creates an SCTP socket and binds it to the local addresses 
-          specified by all <c>{ip,IP}</c> (or synonymously <c>{ifaddr,IP}</c>)
+          specified by all <c>{ip,<anno>IP</anno>}</c> (or synonymously <c>{ifaddr,<anno>IP</anno>}</c>)
           options (this feature is called SCTP multi-homing).
-          The default <c>IP</c> and <c>Port</c> are <c>any</c> 
+          The default <c><anno>IP</anno></c> and <c><anno>Port</anno></c> are <c>any</c>
           and <c>0</c>, meaning bind to all local addresses on any
           one free port.</p>
         <p>A default set of socket <seealso marker="#options">options</seealso>
@@ -345,27 +310,16 @@
       </desc>
     </func>
     <func>
-      <name>recv(sctp_socket()) -&gt; {ok, {FromIP, FromPort, AncData, BinMsg}} | {error, Reason}</name>
-      <name>recv(sctp_socket(), timeout()) -&gt; {ok, {FromIP, FromPort, AncData, Data}} | {error, Reason}</name>
+      <name name="recv" arity="1"/>
+      <name name="recv" arity="2"/>
       <fsummary>Receive a message from a socket</fsummary>
-      <type>
-        <v>FromIP   = ip_address()</v>
-        <v>FromPort = port_number()</v>
-        <v>AncData  = [#sctp_sndrcvinfo{}]</v>
-        <v>Data     = binary() | charlist() | #sctp_sndrcvinfo{} |
-                      #sctp_assoc_change{} | #sctp_paddr_change{} |
-                      #sctp_adaptation_event{} </v>
-        <v>Reason   = posix() | #sctp_send_failed{} | #scpt_paddr_change{} |
-                      #sctp_pdapi_event{} | #sctp_remote_error{} |
-                      #sctp_shutdown_event{}</v>
-      </type>
       <desc>
-        <p>Receives the <c>Data</c> message from any association of the socket.
+        <p>Receives the <c><anno>Data</anno></c> message from any association of the socket.
           If the receive times out <c>{error,timeout</c> is returned.
           The default timeout is <c>infinity</c>.
-          <c>FromIP</c> and <c>FromPort</c> indicate the sender's address.</p>
-        <p><c>AncData</c> is a list of Ancillary Data items which
-          may be received along with the main <c>Data</c>.
+          <c><anno>FromIP</anno></c> and <c><anno>FromPort</anno></c> indicate the sender's address.</p>
+        <p><c><anno>AncData</anno></c> is a list of Ancillary Data items which
+          may be received along with the main <c><anno>Data</anno></c>.
           This list can be empty, or contain a single
           <seealso marker="#record-sctp_sndrcvinfo">#sctp_sndrcvinfo{}</seealso>
           record, if receiving of such ancillary data is enabled
@@ -375,10 +329,10 @@
           provide an easy way of determining the association and stream
           over which the message has been received.
           (An alternative way would be to get the Association ID from the
-          <c>FromIP</c> and <c>FromPort</c> using the
+          <c><anno>FromIP</anno></c> and <c><anno>FromPort</anno></c> using the
           <seealso marker="#option-sctp_get_peer_addr_info">sctp_get_peer_addr_info</seealso> socket option,
           but this would still not produce the Stream number).</p>
-        <p>The actual <c>Data</c> received may be a <c>binary()</c>,
+        <p>The actual <c><anno>Data</anno></c> received may be a <c>binary()</c>,
           or <c>list()</c> of bytes (integers in the range 0 through 255)
           depending on the socket mode, or an SCTP Event.
                     <marker id="sctp_events"></marker>
@@ -476,15 +430,10 @@
       </desc>
     </func>
     <func>
-      <name>send(Socket, SndRcvInfo, Data) -&gt; ok | {error, Reason}</name>
+      <name name="send" arity="3"/>
       <fsummary>Send a message using an <c>#sctp_sndrcvinfo{}</c>record</fsummary>
-      <type>
-        <v>Socket     = sctp_socket()</v>
-        <v>SndRcvInfo = #sctp_sndrcvinfo{}</v>
-        <v>Data       = binary() | iolist()</v>
-      </type>
       <desc>
-        <p>Sends the <c>Data</c> message with all sending parameters from a
+        <p>Sends the <c><anno>Data</anno></c> message with all sending parameters from a
           <seealso marker="#record-sctp_sndrcvinfo">#sctp_sndrcvinfo{}</seealso> record.
           This way, the user can specify the PPID (passed to the remote end)
           and Context (passed to the local SCTP layer) which can be used
@@ -494,21 +443,15 @@
       </desc>
     </func>
     <func>
-      <name>send(Socket, Assoc, Stream, Data) -&gt; ok | {error, Reason}</name>
+      <name name="send" arity="4"/>
       <fsummary>Send a message over an existing association and given stream</fsummary>
-      <type>
-        <v>Socket = sctp_socket()</v>
-        <v>Assoc  = #sctp_assoc_change{} | assoc_id()</v>
-        <v>Stream = integer()</v>
-        <v>Data   = binary() | iolist()</v>
-      </type>
       <desc>
-        <p>Sends <c>Data</c> message over an existing association and given
+        <p>Sends <c><anno>Data</anno></c> message over an existing association and given
           stream.</p>
       </desc>
     </func>
     <func>
-      <name>error_string(integer()) -> ok | string() | undefined</name>
+      <name name="error_string" arity="1"/>
       <fsummary>Translate an SCTP error number into a string</fsummary>
       <desc>
         <p>Translates an SCTP error number from for example