From 265bc740d0abcddee8e7eef2286980f2db3088b0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Tue, 31 Jul 2018 15:19:16 +0200
Subject: Revisit the manual pages for the various modules

---
 doc/src/manual/ranch_tcp.asciidoc | 199 +++++++++++++++++++++++++-------------
 1 file changed, 132 insertions(+), 67 deletions(-)

(limited to 'doc/src/manual/ranch_tcp.asciidoc')

diff --git a/doc/src/manual/ranch_tcp.asciidoc b/doc/src/manual/ranch_tcp.asciidoc
index 6eb7fa3..d01b262 100644
--- a/doc/src/manual/ranch_tcp.asciidoc
+++ b/doc/src/manual/ranch_tcp.asciidoc
@@ -2,16 +2,19 @@
 
 == Name
 
-ranch_tcp - TCP transport module
+ranch_tcp - TCP transport
 
 == Description
 
-The `ranch_tcp` module implements a TCP Ranch transport.
+The module `ranch_tcp` implements a TCP Ranch transport.
 
-Note that due to bugs in OTP up to at least R16B02, it is
-recommended to disable async threads when using the
-`sendfile` function of this transport, as it can make
-the threads stuck indefinitely.
+The function `sendfile` may not work correctly when used
+against files stored in a VirtualBox shared folder.
+
+== Exports
+
+The module `ranch_tcp` implements the interface defined
+by link:man:ranch_transport(3)[ranch_transport(3)].
 
 == Types
 
@@ -20,44 +23,36 @@ the threads stuck indefinitely.
 [source,erlang]
 ----
 opt() = {backlog, non_neg_integer()}
-	| {buffer, non_neg_integer()}
-	| {delay_send, boolean()}
-	| {dontroute, boolean()}
-	| {exit_on_close, boolean()}
-	| {fd, non_neg_integer()}
-	| {high_msgq_watermark, non_neg_integer()}
-	| {high_watermark, non_neg_integer()}
-	| inet
-	| inet6
-	| {ip, inet:ip_address()}
-	| {ipv6_v6only, boolean()}
-	| {keepalive, boolean()}
-	| {linger, {boolean(), non_neg_integer()}}
-	| {low_msgq_watermark, non_neg_integer()}
-	| {low_watermark, non_neg_integer()}
-	| {nodelay, boolean()}
-	| {port, inet:port_number()}
-	| {priority, integer()}
-	| {raw, non_neg_integer(), non_neg_integer(), binary()}
-	| {recbuf, non_neg_integer()}
-	| {send_timeout, timeout()}
-	| {send_timeout_close, boolean()}
-	| {sndbuf, non_neg_integer()}
-	| {tos, integer()}
+      | {buffer, non_neg_integer()}
+      | {delay_send, boolean()}
+      | {dontroute, boolean()}
+      | {exit_on_close, boolean()}
+      | {fd, non_neg_integer()}
+      | {high_msgq_watermark, non_neg_integer()}
+      | {high_watermark, non_neg_integer()}
+      | inet
+      | inet6
+      | {ip, inet:ip_address()}
+      | {ipv6_v6only, boolean()}
+      | {keepalive, boolean()}
+      | {linger, {boolean(), non_neg_integer()}}
+      | {low_msgq_watermark, non_neg_integer()}
+      | {low_watermark, non_neg_integer()}
+      | {nodelay, boolean()}
+      | {port, inet:port_number()}
+      | {priority, integer()}
+      | {raw, non_neg_integer(), non_neg_integer(), binary()}
+      | {recbuf, non_neg_integer()}
+      | {send_timeout, timeout()}
+      | {send_timeout_close, boolean()}
+      | {sndbuf, non_neg_integer()}
+      | {tos, integer()}
 ----
 
 Listen options.
 
-This does not represent the entirety of the options that can
-be set on the socket, but only the options that may be
-set independently of protocol implementation.
-
-=== opts() = [opt()]
-
-List of listen options.
-
-Option descriptions
--------------------
+Note that additional options may be set by the protocol
+module using `Transport:setopts/2`.
 
 None of the options are required.
 
@@ -65,62 +60,132 @@ Please consult the `gen_tcp` and `inet` manuals for a more
 thorough description of these options. This manual only aims
 to provide a short description along with what the defaults
 are. Defaults may be different in Ranch compared to `gen_tcp`.
-Defaults are given next to the option name.
+Defaults are given next to the option name:
 
 backlog (1024)::
-	Max length of the queue of pending connections.
+
+Max length of the queue of pending connections.
+
 buffer::
-	Size of the buffer used by the Erlang driver. Default is system-dependent.
+
+Size of the buffer used by the Erlang driver. Default
+is system-dependent.
+
 delay_send (false)::
-	Always queue packets before sending, to send fewer, larger packets over the network.
+
+Always queue data before sending, to send fewer, larger
+packets over the network.
+
 dontroute (false)::
-	Don't send via a gateway, only send to directly connected hosts.
+
+Don't send via a gateway, only send to directly connected hosts.
+
 exit_on_close (true)::
-	Disable to allow sending data after a close has been detected.
+
+Disable to allow sending data after a close has been detected.
+
 fd::
-	File descriptor of the socket, if it was opened externally.
+
+File descriptor of the socket, if it was opened externally.
+
 high_msgq_watermark (8192)::
-	Limit in the amount of data in the socket message queue before the socket queue becomes busy.
+
+Limit in the amount of data in the socket message queue before
+the queue becomes busy.
+
 high_watermark (8192)::
-	Limit in the amount of data in the ERTS socket implementation's queue before the socket becomes busy.
+
+Limit in the amount of data in the ERTS socket implementation's
+queue before the socket becomes busy.
+
 inet::
-	Set up the socket for IPv4.
+
+Set up the socket for IPv4.
+
 inet6::
-	Set up the socket for IPv6.
+
+Set up the socket for IPv6.
+
 ip::
-	Interface to listen on. Listen on all interfaces by default.
+
+Interface to listen on. Listen on all interfaces by default.
+
 ipv6_v6only (false)::
-	Listen on IPv4 and IPv6 (false) or only on IPv6 (true). Use with inet6.
+
+Listen on IPv4 and IPv6 (false) or only on IPv6 (true).
+Use with inet6.
+
 keepalive (false)::
-	Enable sending of keep-alive messages.
+
+Enable sending of keep-alive messages.
+
 linger ({false, 0})::
-	Whether to wait and how long to flush data sent before closing the socket.
+
+Whether to wait and how long to flush data sent before closing
+the socket.
+
 low_msgq_watermark (4096)::
-	Amount of data in the socket message queue before the socket queue leaves busy state.
+
+Amount of data in the socket message queue before the queue
+leaves busy state.
+
 low_watermark (4096)::
-	Amount of data in the ERTS socket implementation's queue before the socket leaves busy state.
+
+Amount of data in the ERTS socket implementation's queue
+before the socket leaves busy state.
+
 nodelay (true)::
-	Whether to enable TCP_NODELAY.
+
+Whether to enable TCP_NODELAY.
+
 port (0)::
-	TCP port number to listen on. 0 means a random port will be used.
+
+TCP port number to listen on. 0 means a random port will be used.
+
 priority (0)::
-	Priority value for all packets to be sent by this socket.
+
+Priority value for all packets to be sent on this socket.
+
 recbuf::
-	Minimum size of the socket's receive buffer. Default is system-dependent.
+
+Minimum size of the socket's receive buffer.
+Default is system-dependent.
+
 send_timeout (30000)::
-	How long the send call may wait for confirmation before returning.
+
+How long the send call may wait for confirmation before returning.
+
 send_timeout_close (true)::
-	Whether to close the socket when the confirmation wasn't received.
+
+Whether to close the socket when the confirmation wasn't received.
+
 sndbuf::
-	Minimum size of the socket's send buffer. Default is system-dependent.
+
+Minimum size of the socket's send buffer.
+Default is system-dependent.
+
 tos::
-	Value for the IP_TOS IP level option. Use with caution.
+
+Value for the IP_TOS IP level option. Use with caution.
 
 In addition, the `raw` option can be used to set system-specific
 options by specifying the protocol level, the option number and
 the actual option value specified as a binary. This option is not
 portable. Use with caution.
 
-== Exports
+=== opts()
+
+[source,erlang]
+----
+opts() :: [opt()]
+----
+
+List of listen options.
+
+== See also
 
-None.
+link:man:ranch(7)[ranch(7)],
+link:man:ranch_transport(3)[ranch_transport(3)],
+link:man:ranch_ssl(3)[ranch_ssl(3)],
+gen_tcp(3),
+inet(3)
-- 
cgit v1.2.3

