From 30604262b5934b38e9f55f0d3ef44f8aed5310de Mon Sep 17 00:00:00 2001
From: juhlig <j.uhlig@mailingwork.de>
Date: Mon, 27 May 2019 15:20:37 +0200
Subject: Use transport options in ranch_transport:listen/1 callbacks

The callback `ranch_transport:listen/1` has changed to accept a map
of transport options instead of socket options.
---
 doc/src/guide/upcoming_2.0_changes.asciidoc |  5 ++++
 doc/src/manual/ranch.asciidoc               | 43 +++++++++++++++++++----------
 doc/src/manual/ranch_transport.asciidoc     |  7 +++--
 3 files changed, 38 insertions(+), 17 deletions(-)

(limited to 'doc')

diff --git a/doc/src/guide/upcoming_2.0_changes.asciidoc b/doc/src/guide/upcoming_2.0_changes.asciidoc
index d743090..378d0a6 100644
--- a/doc/src/guide/upcoming_2.0_changes.asciidoc
+++ b/doc/src/guide/upcoming_2.0_changes.asciidoc
@@ -5,6 +5,11 @@ The following changes will be done in Ranch 2.0. In most
 cases an alternative is already available in the most
 recent Ranch version.
 
+* The callback function `ranch_transport:listen/1` and its
+  implementations in `ranch_tcp` and `ranch_ssl` have changed
+  to accept a map of transport options instead of socket
+  options.
+
 * The function `ranch:start_listener/6` has been deprecated
   in favor of `ranch:start_listener/5`. The number of acceptors
   was removed and will be taken from the transport options.
diff --git a/doc/src/manual/ranch.asciidoc b/doc/src/manual/ranch.asciidoc
index 549bb78..065ded3 100644
--- a/doc/src/manual/ranch.asciidoc
+++ b/doc/src/manual/ranch.asciidoc
@@ -67,7 +67,30 @@ code.
 
 [source,erlang]
 ----
-opts() = any() | #{
+opts() = any() | transport_opts(any())
+----
+
+Transport or socket options.
+
+It is possible to give the full transport options in a map
+(see `transport_opts(SocketOpts)`), or only the socket options
+(assuming they are not a map and no Ranch-specific option
+needs to be given).
+
+=== ref()
+
+[source,erlang]
+----
+ref() = any()
+----
+
+Unique name used to refer to a listener.
+
+=== transport_opts(SocketOpts)
+
+[source,erlang]
+----
+transport_opts(SocketOpts) = #{
     connection_type   => worker | supervisor,
     handshake_timeout => timeout(),
     max_connections   => max_conns(),
@@ -75,16 +98,14 @@ opts() = any() | #{
     num_acceptors     => pos_integer(),
     num_conns_sups    => pos_integer(),
     shutdown          => timeout() | brutal_kill,
-    socket_opts       => any()
+    socket_opts       => SocketOpts
 }
 ----
 
 Transport options.
 
 The transport options are a combination of Ranch-specific
-options and socket options. Socket options may be given
-directly (assuming they are not a map and no Ranch-specific
-option needs to be given) or as part of `socket_opts`.
+options and transport-specific socket options.
 
 None of the options are required.
 
@@ -120,20 +141,12 @@ Maximum allowed time for children to stop on listener shutdown.
 
 socket_opts::
 
-Socket options given to `Transport:listen/1`. Please refer to the
+Socket options to be used by `Transport:listen/1`. Please refer to the
 documentation of the transport module you are using for more details.
 
-=== ref()
-
-[source,erlang]
-----
-ref() = any()
-----
-
-Unique name used to refer to a listener.
-
 == Changelog
 
+* *2.0*: The type `transport_opts(SocketOpts)` was added.
 * *2.0*: The function `ranch:accept_ack/1` was removed in favor of
          link:man:ranch:handshake(3)[ranch:handshake(3)].
 * *2.0*: The option `max_connections` is now per connection supervisor.
diff --git a/doc/src/manual/ranch_transport.asciidoc b/doc/src/manual/ranch_transport.asciidoc
index 2d59e82..78468b3 100644
--- a/doc/src/manual/ranch_transport.asciidoc
+++ b/doc/src/manual/ranch_transport.asciidoc
@@ -101,11 +101,12 @@ be upgraded to a `ranch_ssl` one using this function.
 
 [source,erlang]
 ----
-listen(SockOpts :: any())
+listen(TransportOpts :: ranch:transport_opts(any()))
     -> {ok, LSocket :: socket()} | {error, atom()}
 ----
 
-Create a socket that listens on the given port.
+Create a socket that listens on the port given in the
+socket options.
 
 The port may not be specified or may be set to 0, which
 means a random available port number will be chosen.
@@ -292,6 +293,8 @@ The exact type will vary depending on the transport module.
 
 == Changelog
 
+* *2.0*: The callback `listen/1` has changed to accept a map of
+         transport options instead of socket options.
 * *2.0*: The callback `messages/0` return value was updated to
          include the passive message for `{active, N}`.
 * *1.6*: The `socket()` type was added for documentation purposes.
-- 
cgit v1.2.3