Merge branch 'dev' of super:otp into dev

* 'dev' of super:otp: (166 commits)
  Corrected documentation error and added examples to Users Guide
  In TLS 1.1, failure to properly close a connection no longer requires that a session not be resumed.  This is a change from TLS 1.0 to conform with widespread implementation practice.  Erlang ssl will now in TLS 1.0 conform to the widespread implementation practice instead of the specification to avoid performance issues.
  Add escript to bootstrap/bin
  Remove unused variable warning in inet_res
  Remove unused variable in epmd_port
  Remove compiler warnings in inet_drv
  Add SASL test suite
  Allow same module name in multiple applications if explicitely excluded
  Fix bugs concerning the option report_missing_types
  Fix default encoding in SAX parser.
  re: remove gratuitous "it " in manpage
  Spelling in (backward *compatibility*) comment.
  Improve erl_docgen's support for Dialyzer specs and types
  dialyzer warning on mnesia_tm
  Add documentation text about majority checking
  add mnesia_majority_test suite
  where_to_wlock optimization + change_table_majority/2
  bug in mnesia_tm:needs_majority/2
  optimize sticky_lock maj. check
  check majority for sticky locks
  ...

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