Clarify {get,set}_{protocol,transport}_options docs

Clarifications and examples.

3 files changed, 39 insertions, 1 deletions

diff --git a/doc/src/manual/ranch.get_transport_options.asciidoc b/doc/src/manual/ranch.get_transport_options.asciidoc
index 438df90..0214e0f 100644
--- a/doc/src/manual/ranch.get_transport_options.asciidoc
+++ b/doc/src/manual/ranch.get_transport_options.asciidoc
@@ -9,7 +9,7 @@ ranch:get_transport_options - Get the current transport options
 [source,erlang]
 ----
 get_transport_options(Ref :: ranch:ref())
-    -> TransOpts :: any()
+    -> TransOpts :: ranch:transport_opts(any())
 ----
 
 Get the current transport options.
@@ -24,6 +24,11 @@ The listener name.
 
 The current transport options are returned.
 
+If the transport options were specified as only socket options (not a map) using
+link:man:ranch:start_listener(3)[ranch:start_listener(3)] or
+link:man:ranch:set_transport_options(3)[ranch:set_transport_options(3)], they
+are returned as `#{socket_opts => SocketOpts}`.
+
 == Examples
 
 .Get the current transport options
diff --git a/doc/src/manual/ranch.set_protocol_options.asciidoc b/doc/src/manual/ranch.set_protocol_options.asciidoc
index 1851fab..36370c8 100644
--- a/doc/src/manual/ranch.set_protocol_options.asciidoc
+++ b/doc/src/manual/ranch.set_protocol_options.asciidoc
@@ -18,6 +18,11 @@ Set the protocol options.
 The change will be applied immediately for all new connections.
 Old connections will not receive the new options.
 
+Note that the complete set of protocol options is replaced. To update a subset
+of the options, it is recommended to get the current protocol options using
+link:man:ranch:get_protocol_options(3)[ranch:get_protocol_options(3)], update
+them and then set them back using this function.
+
 == Arguments
 
 Ref::
@@ -40,6 +45,14 @@ The atom `ok` is always returned. It can be safely ignored.
 ranch:set_protocol_options(example, ProtoOpts).
 ----
 
+.Update some of the protocol options
+[source,erlang]
+----
+ProtoOpts0 = ranch:get_protocol_options(example),
+ProtoOpts = ProtoOpts0#{request_timeout => 2000},
+ranch:set_protocol_options(example, ProtoOpts).
+----
+
 == See also
 
 link:man:ranch:get_protocol_options(3)[ranch:get_protocol_options(3)],
diff --git a/doc/src/manual/ranch.set_transport_options.asciidoc b/doc/src/manual/ranch.set_transport_options.asciidoc
index 146f21e..8c2eacb 100644
--- a/doc/src/manual/ranch.set_transport_options.asciidoc
+++ b/doc/src/manual/ranch.set_transport_options.asciidoc
@@ -15,6 +15,11 @@ set_transport_options(Ref       :: ranch:ref(),
 
 Set the transport options.
 
+The complete set of transport options is replaced. To update a subset of the
+transport options, it is recommended to get the current transport options using
+link:man:ranch:get_transport_options(3)[ranch:get_transport_options(3)], update
+them and then set them back using this function.
+
 Changes to the following options will take effect...
 
 * immediately:
@@ -66,6 +71,21 @@ ok = ranch:set_transport_options(Ref, TransOpts),
 ok = ranch:resume_listener(Ref).
 ----
 
+.Update the listener TCP port within the `socket_opts` transport option
+[source,erlang]
+----
+Ref = example,
+
+TransOpts0 = ranch:get_transport_options(Ref),
+#{socket_opts = SocketOpts0} = TransOpts0,
+SocketOpts = [{port, 12345}|proplists:delete(port, SocketOpts0)],
+TransOpts = TransOpts0#{socket_opts = SocketOpts},
+
+ok = ranch:suspend_listener(Ref),
+ok = ranch:set_transport_options(Ref, TransOpts),
+ok = ranch:resume_listener(Ref).
+----
+
 == See also
 
 link:man:ranch:suspend_listener(3)[ranch:suspend_listener(3)],