From 64c4668a65195283c7dbc24a677f8d3d46ac5513 Mon Sep 17 00:00:00 2001
From: Micael Karlberg <bmk@erlang.org>
Date: Thu, 2 May 2019 15:08:00 +0200
Subject: [esock|doc] Update with regard to the new select returns

---
 erts/doc/src/socket.xml       | 30 ++++++++++++++++-----
 erts/doc/src/socket_usage.xml | 63 +++++++++++++++++++++++++++++++++++++------
 2 files changed, 78 insertions(+), 15 deletions(-)

(limited to 'erts/doc')

diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml
index f9dd9575f4..48e91e93a7 100644
--- a/erts/doc/src/socket.xml
+++ b/erts/doc/src/socket.xml
@@ -47,24 +47,40 @@
       <seealso marker="#recv_async"><c>recv/3</c></seealso>
       function with Timeout set to <c>nowait</c> (<c>recv(Sock, 0, nowait)</c>)
       when there is actually nothing to read, it will return with
-      <c>{ok, SelectInfo}</c>. When data eventually arrives a 'select' message
-      will be sent to the caller:
+      <c>{ok, </c>
+      <seealso marker="#type-select_info"><c>SelectInfo</c></seealso><c>}</c>.
+      When data eventually arrives a 'select' message
+      will be sent to the caller: </p>
+      <!--
       <list type="ordered">
 	<item><c>{'$socket', Sock, select, Info}</c></item>
       </list>
-      The caller can now make another
+      -->
+      <taglist>
+	<!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL -->
+	<tag></tag>
+	<item><c>{'$socket', Sock, select, Info}</c></item>
+      </taglist>
+      <p>The caller can now make another
       call to the recv function and now expect data.</p>
       <p>Note that all other users are <em>locked out</em> until the
       'current user' has called the function (recv in this case).</p>
       <p>Another message the user must be prepared for (when making asynchronous
-      calls) is the <c>abort</c> message:
+      calls) is the <c>abort</c> message:</p>
+      <!--
       <list type="ordered">
-	<item><c>{'$socket', Sock, abort, Reason}</c></item>
+	<item><c>{'$socket', Sock, abort, Info}</c></item>
       </list>
-      This message indicates
+      -->
+      <taglist>
+	<!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL -->
+	<tag></tag>
+	<item><c>{'$socket', Sock, abort, Info}</c></item>
+      </taglist>
+      <p>This message indicates
       that the (asynchronous) operation has been aborted.
       If, for instance, the socket has been
-      closed (by another process), <c>Reason</c> will be <c>{Ref, closed}</c>. </p>
+      closed (by another process), <c>Info</c> will be <c>{Ref, closed}</c>. </p>
     </note>
     <note>
       <p>There is currently <em>no</em> support for Windows. </p>
diff --git a/erts/doc/src/socket_usage.xml b/erts/doc/src/socket_usage.xml
index fcfe9b54ec..9d8141b822 100644
--- a/erts/doc/src/socket_usage.xml
+++ b/erts/doc/src/socket_usage.xml
@@ -54,25 +54,72 @@
       <seealso marker="socket#recv_async"><c>recv/3</c></seealso>
       function with Timeout set to <c>nowait</c> (i.e. <c>recv(Sock, 0, nowait)</c>)
       when there is actually nothing to read, it will return with
-      <c>{ok, SelectInfo}</c>. When data eventually arrives a 'select message'
-      will be sent to the caller:
+      <c>{ok, </c>
+      <seealso marker="socket#type-select_info"><c>SelectInfo</c></seealso><c>}</c>.
+      When data eventually arrives a 'select message'
+      will be sent to the caller:</p>
+      <!--
       <list type="ordered">
 	<item><c>{'$socket', Sock, select, Info}</c></item>
       </list>
-      The caller can then make another
+      -->
+      <taglist>
+	<!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL -->
+	<tag></tag>
+	<item><c>{'$socket', Sock, select, Info}</c></item>
+      </taglist>
+      <p>The caller can then make another
       call to the recv function and now expect data.</p>
-      <p>The user must also be prepared to receive an abort message:
+      <p>The user must also be prepared to receive an abort message: </p>
+      <!--
       <list type="ordered">
-	<item><c>{'$socket', Sock, abort, Reason}</c></item>
+	<item><c>{'$socket', Sock, abort, Info}</c></item>
       </list>
-      If the operation is aborted
+      -->
+      <taglist>
+	<!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL -->
+	<tag></tag>
+	<item><c>{'$socket', Sock, abort, Info}</c></item>
+      </taglist>
+      <p>If the operation is aborted
       for whatever reason (e.g. if the socket is closed "by someone else").
-      The <c>Reason</c> part contains the abort reason (in case the socket
-      has been closed <c>Reason = {Ref, closed}</c>). </p>
+      The <c>Info</c> part contains the abort reason (in this case that
+      the socket has been closed <c>Info = {Ref, closed}</c>). </p>
       <p>Note that all other users are <em>locked out</em> until the
       'current user' has called the function (recv in this case). So either
       immediately call the function or
       <seealso marker="socket#cancel/2"><c>cancel</c></seealso>. </p>
+      <p>The general form of the 'socket' message is: </p>
+      <!--
+      <list type="ordered">
+	<item>
+	  <c>{'$socket', Socket :: socket(), Tag :: atom(), Info :: term()}</c>
+	</item>
+      </list>
+      -->
+      <taglist>
+	<!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL -->
+	<tag></tag>
+	<item><c>{'$socket', Sock :: socket(), Tag :: atom(), Info :: term()}</c></item>
+      </taglist>
+      <p>Where the format of <c>Info</c> is a function of <c>Tag</c>:</p>
+      <table>
+	<row>
+	  <cell><em>Tag</em></cell>
+	  <cell><em>Info value type</em></cell>
+	</row>
+	<row>
+	  <cell>select</cell>
+	  <cell>reference()</cell>
+	</row>
+	<row>
+	  <cell>abort</cell>
+	  <cell>{reference(), Reason :: term()}</cell>
+	</row>
+	<tcaption>socket message info value type</tcaption>
+      </table>
+      <p>The <c>reference()</c> is the same as was received in the
+      <seealso marker="socket#type-select_info"><c>SelectInfo</c></seealso>. </p>
     </section>
   </section>
 
-- 
cgit v1.2.3