Update manual for the cowboy module

This commit separates the documentation of the functions into
separate manual pages, with at least one example per function
and a lot more details about parameters, return values and
related functions and modules. It also includes a changelog
indicating when the function was added or changed.

The inspiration for this comes mainly from the PHP documentation
and feedback from users.

5 files changed, 452 insertions, 50 deletions

diff --git a/doc/src/manual/cowboy.asciidoc b/doc/src/manual/cowboy.asciidoc
index 10e3696..6aad091 100644
--- a/doc/src/manual/cowboy.asciidoc
+++ b/doc/src/manual/cowboy.asciidoc
@@ -9,80 +9,91 @@ cowboy - HTTP server
 The `cowboy` module provides convenience functions for
 manipulating Ranch listeners.
 
+== Exports
+
+* link:man:cowboy:start_clear(3)[cowboy:start_clear(3)] - Listen for connections using plain TCP
+* link:man:cowboy:start_tls(3)[cowboy:start_tls(3)] - Listen for connections using TLS
+* link:man:cowboy:stop_listener(3)[cowboy:stop_listener(3)] - Stop the given listener
+* link:man:cowboy:set_env(3)[cowboy:set_env(3)] - Update a listener's environment value
+
 == Types
 
-=== fields() = [Field]
+=== fields()
 
 [source,erlang]
 ----
-Field = atom()
-	| {atom(), cowboy_constraints:constraint() | [cowboy_constraints:constraint()]}
-	| {atom(), cowboy_constraints:constraint() | [cowboy_constraints:constraint()], any()}]
+fields() :: [Name
+           | {Name, Constraints}
+           | {Name, Constraints, Default}]
+
+Name :: atom()
+Constraints :: Constraint | [Constraint]
+Constraint :: cowboy_constraints:constraint()
+Default :: any()
 ----
 
-Fields for match operations. Constraint(s) and default value are optional.
-
-=== http_headers() = [{binary(), iodata()}]
-
-HTTP headers as a list of key/values.
-
-=== http_status() = non_neg_integer() | binary()
+Fields description for match operations.
 
-HTTP status.
+This type is used in link:man:cowboy_router(3)[cowboy_router]
+for matching bindings and in the match functions found in
+link:man:cowboy_req(3)[cowboy_req].
 
-A binary status can be used to set a custom message.
+=== http_headers()
 
-=== http_version() = \'HTTP/1.1' | \'HTTP/1.0'
-
-HTTP version.
-
-=== `onresponse_fun() = fun((http_status(), http_headers(), iodata(), cowboy_req:req()) -> cowboy_req:req())`
-
-Fun called immediately before sending the response.
+[source,erlang]
+----
+http_headers() :: #{binary() => iodata()}
+----
 
-It can perform any operation on the Req object, including
-reading the request body or replying. If a reply is sent, it
-overrides the reply initially sent. The callback will not be
-called again for the new reply.
+HTTP headers.
 
-== Exports
+=== http_status()
 
-=== start_http(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()}
+[source,erlang]
+----
+http_status() :: non_neg_integer() | binary()
+----
 
-Ref = ranch:ref():: Listener name.
-NbAcceptors = non_neg_integer():: Number of acceptor processes.
-TransOpts = ranch_tcp:opts():: TCP transport options.
-ProtoOpts = cowboy_protocol:opts():: HTTP protocol options.
+HTTP response status.
 
-Start listening for HTTP connections. Returns the pid for this
-listener's supervisor.
+A binary status can be used to set a reason phrase. Note
+however that HTTP/2 only sends the status code and drops
+the reason phrase entirely.
 
-=== start_https(Ref, NbAcceptors, TransOpts, ProtoOpts) -> {ok, pid()}
+=== http_version()
 
-Ref = ranch:ref():: Listener name.
-NbAcceptors = non_neg_integer():: Number of acceptor processes.
-TransOpts = ranch_ssl:opts():: SSL transport options.
-ProtoOpts = cowboy_protocol:opts():: HTTP protocol options.
+[source,erlang]
+----
+http_version() :: 'HTTP/2' | 'HTTP/1.1' | 'HTTP/1.0'
+----
 
-Start listening for HTTPS connections. Returns the pid for this
-listener's supervisor.
+HTTP version.
 
-=== stop_listener(Ref) -> ok | {error, not_found}
+Note that semantically, HTTP/1.1 and HTTP/2 are equivalent.
 
-Ref = ranch:ref():: Listener name.
+=== opts()
 
-Stop a previously started listener.
+[source,erlang]
+----
+opts() :: map()
+----
 
-=== set_env(Ref, Name, Value) -> ok
+Options for the HTTP/1.1, HTTP/2 and Websocket protocols.
 
-Ref = ranch:ref():: Listener name.
-Name = atom():: Name of environment value.
-Value = any():: Environment value.
+The protocol options are in a map containing all the options for
+the different protocols that may be involved when connecting
+to the listener, including HTTP/1.1 and HTTP/2 but also
+subprotocols like Websocket.
+// @todo For Websocket this might change in the future.
 
-Set or update an environment value for an already running listener.
-This will take effect on all subsequent connections.
+The HTTP/1.1 options are documented in the
+link:man:cowboy_http(3)[cowboy_http(3)] manual;
+the HTTP/2 options in
+link:man:cowboy_http2(3)[cowboy_http2(3)];
+and the Websocket options in
+link:man:cowboy_websocket(3)[cowboy_websocket(3)].
 
 == See also
 
-The http://ninenines.eu/docs/en/ranch/HEAD/guide[Ranch guide]
-provides detailed information about how listeners work.
+link:man:cowboy(7)[cowboy(7)],
+link:man:ranch(3)[ranch(3)]
diff --git a/doc/src/manual/cowboy.set_env.asciidoc b/doc/src/manual/cowboy.set_env.asciidoc
new file mode 100644
index 0000000..0e67e3e
--- /dev/null
+++ b/doc/src/manual/cowboy.set_env.asciidoc
@@ -0,0 +1,79 @@
+= cowboy:set_env(3)
+
+== Name
+
+cowboy:set_env - Update a listener's environment value
+
+== Description
+
+[source,erlang]
+----
+set_env(Name  :: ranch:ref(),
+        Key   :: atom(),
+        Value :: any())
+    -> ok
+----
+
+Set or update an environment value for a previously started
+listener.
+
+This is most useful for updating the routes dynamically,
+without having to restart the listener.
+
+The new value will only be available to new connections.
+Pre-existing connections will still use the old value.
+
+== Arguments
+
+Name::
+
+The name of the listener to update.
++
+The name of the listener is the first argument given to the
+link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
+link:man:cowboy:start_tls(3)[cowboy:start_tls(3)] or
+link:man:ranch:start_listener(3)[ranch:start_listener(3)] function.
+
+Key::
+
+The key in the environment map. Common keys include `dispatch`
+and `middlewares`.
+
+Value::
+
+The new value.
+
+The type of the value differs depending on the key.
+
+== Return value
+
+The atom `ok` is returned on success.
+
+An `exit:badarg` exception is thrown when the listener does
+not exist.
+
+== Changelog
+
+* *1.0*: Function introduced.
+
+== Examples
+
+.Update a listener's routes
+[source,erlang]
+----
+Dispatch = cowboy_router:compile([
+    {'_', [
+        {"/", toppage_h, []},
+		{"/ws", websocket_h, []}
+    ]}
+]),
+
+cowboy:set_env(example, dispatch, Dispatch).
+----
+
+== See also
+
+link:man:cowboy(3)[cowboy(3)],
+link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
+link:man:cowboy:start_tls(3)[cowboy:start_tls(3)],
+link:man:ranch:set_protocol_options(3)[ranch:set_protocol_options(3)]
diff --git a/doc/src/manual/cowboy.start_clear.asciidoc b/doc/src/manual/cowboy.start_clear.asciidoc
new file mode 100644
index 0000000..4903426
--- /dev/null
+++ b/doc/src/manual/cowboy.start_clear.asciidoc
@@ -0,0 +1,126 @@
+= cowboy:start_clear(3)
+
+== Name
+
+cowboy:start_clear - Listen for connections using plain TCP
+
+== Description
+
+[source,erlang]
+----
+start_clear(Name          :: ranch:ref(),
+            NumAcceptors  :: non_neg_integer(),
+            TransportOpts :: ranch_tcp:opts(),
+            ProtocolOpts  :: opts())
+    -> {ok, ListenerPid :: pid()}
+     | {error, any()}
+----
+
+Start listening for connections over a clear TCP channel.
+
+Both HTTP/1.1 and HTTP/2 are supported on this listener.
+HTTP/2 has two methods of establishing a connection over
+a clear TCP channel. Both the upgrade and the prior knowledge
+methods are supported.
+
+== Arguments
+
+Name::
+
+The listener name is used to refer to this listener in
+future calls, for example when stopping it or when
+updating the routes defined.
++
+It can be any Erlang term. An atom is generally good enough,
+for example `api`, `my_app_clear` or `my_app_tls`.
+
+NumAcceptors::
+
+The number of acceptors is the number of processes that
+will accept connections. Tweak this value to improve the
+accept rate for incoming connections.
++
+The ideal value is between 10 and 100 on most systems.
+Larger values may have the opposite effect and reduce the
+accept rate. It's generally safe to start with a value of
+100 (or 10 on low memory systems). Then, when accept rates
+become a concern, measure the performance and update the
+value accordingly.
++
+This value is unrelated to the maximum number of concurrent
+connections.
+
+TransportOpts::
+
+The transport options are where the TCP options, including
+the listener's port number, are defined. Transport options
+are provided as a list of keys and values, for example
+`[{port, 8080}]`.
++
+The available options are documented in the
+link:man:ranch_tcp(3)[ranch_tcp(3)] manual.
+
+ProtocolOpts::
+
+The protocol options are in a map containing all the options for
+the different protocols that may be involved when connecting
+to the listener, including HTTP/1.1 and HTTP/2 but also
+subprotocols like Websocket.
+// @todo For Websocket this might change in the future.
++
+The HTTP/1.1 options are documented in the
+link:man:cowboy_http(3)[cowboy_http(3)] manual;
+the HTTP/2 options in
+link:man:cowboy_http2(3)[cowboy_http2(3)];
+and the Websocket options in
+link:man:cowboy_websocket(3)[cowboy_websocket(3)].
+
+== Return value
+
+An ok tuple is returned on success. It contains the pid of
+the top-level supervisor for the listener.
+
+An error tuple is returned on error. The error reason may
+be any Erlang term.
+
+A common error is `eaddrinuse`. It indicates that the port
+configured for Cowboy is already in use.
+
+== Changelog
+
+* *2.0*: HTTP/2 support added.
+* *2.0*: Function introduced. Replaces `cowboy:start_http/4`.
+
+== Examples
+
+.Start a listener
+[source,erlang]
+----
+Dispatch = cowboy_router:compile([
+    {'_', [
+        {"/", toppage_h, []}
+    ]}
+]),
+
+{ok, _} = cowboy:start_clear(example, 100, [{port, 8080}], #{
+    env => #{dispatch => Dispatch}
+}).
+----
+
+.Start a listener on a random port
+[source,erlang]
+----
+Name = example,
+
+{ok, _} = cowboy:start_clear(Name, 100, [], #{
+    env => #{dispatch => Dispatch}
+}),
+
+Port = ranch:get_port(Name).
+----
+
+== See also
+
+link:man:cowboy(3)[cowboy(3)],
+link:man:cowboy:start_tls(3)[cowboy:start_tls(3)],
+link:man:ranch(3)[ranch(3)]
diff --git a/doc/src/manual/cowboy.start_tls.asciidoc b/doc/src/manual/cowboy.start_tls.asciidoc
new file mode 100644
index 0000000..b85abe6
--- /dev/null
+++ b/doc/src/manual/cowboy.start_tls.asciidoc
@@ -0,0 +1,131 @@
+= cowboy:start_tls(3)
+
+== Name
+
+cowboy:start_tls - Listen for connections using TLS
+
+== Description
+
+[source,erlang]
+----
+start_tls(Name          :: ranch:ref(),
+          NumAcceptors  :: non_neg_integer(),
+          TransportOpts :: ranch_ssl:opts(),
+          ProtocolOpts  :: opts())
+    -> {ok, ListenerPid :: pid()}
+     | {error, any()}
+----
+
+Start listening for connections over a secure TLS channel.
+
+Both HTTP/1.1 and HTTP/2 are supported on this listener.
+The ALPN TLS extension must be used to initiate an HTTP/2
+connection.
+
+== Arguments
+
+Name::
+
+The listener name is used to refer to this listener in
+future calls, for example when stopping it or when
+updating the routes defined.
++
+It can be any Erlang term. An atom is generally good enough,
+for example `api`, `my_app_clear` or `my_app_tls`.
+
+NumAcceptors::
+
+The number of acceptors is the number of processes that
+will accept connections. Tweak this value to improve the
+accept rate for incoming connections.
++
+The ideal value is between 10 and 100 on most systems.
+Larger values may have the opposite effect and reduce the
+accept rate. It's generally safe to start with a value of
+100 (or 10 on low memory systems). Then, when accept rates
+become a concern, measure the performance and update the
+value accordingly.
++
+This value is unrelated to the maximum number of concurrent
+connections.
+
+TransportOpts::
+
+The transport options are where the TCP options, including
+the listener's port number, are defined. They also contain
+the TLS options, like the server's certificate. Transport options
+are provided as a list of keys and values, for example
+`[{port, 8443}, {certfile, "path/to/cert.pem"}]`.
++
+The available options are documented in the
+link:man:ranch_ssl(3)[ranch_ssl(3)] manual.
+
+ProtocolOpts::
+
+The protocol options are in a map containing all the options for
+the different protocols that may be involved when connecting
+to the listener, including HTTP/1.1 and HTTP/2 but also
+subprotocols like Websocket.
+// @todo For Websocket this might change in the future.
++
+The HTTP/1.1 options are documented in the
+link:man:cowboy_http(3)[cowboy_http(3)] manual;
+the HTTP/2 options in
+link:man:cowboy_http2(3)[cowboy_http2(3)];
+and the Websocket options in
+link:man:cowboy_websocket(3)[cowboy_websocket(3)].
+
+== Return value
+
+An ok tuple is returned on success. It contains the pid of
+the top-level supervisor for the listener.
+
+An error tuple is returned on error. The error reason may
+be any Erlang term.
+
+A common error is `eaddrinuse`. It indicates that the port
+configured for Cowboy is already in use.
+
+== Changelog
+
+* *2.0*: HTTP/2 support added.
+* *2.0*: Function introduced. Replaces `cowboy:start_https/4`.
+
+== Examples
+
+.Start a listener
+[source,erlang]
+----
+Dispatch = cowboy_router:compile([
+    {'_', [
+        {"/", toppage_h, []}
+    ]}
+]),
+
+{ok, _} = cowboy:start_tls(example, 100, [
+    {port, 8443},
+    {cert, "path/to/cert.pem"}
+], #{
+    env => #{dispatch => Dispatch}
+}).
+----
+
+.Start a listener on a random port
+[source,erlang]
+----
+Name = example,
+
+{ok, _} = cowboy:start_tls(Name, 100, [
+    {cert, "path/to/cert.pem"}
+], #{
+    env => #{dispatch => Dispatch}
+}),
+
+Port = ranch:get_port(Name).
+----
+
+== See also
+
+link:man:cowboy(3)[cowboy(3)],
+link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
+link:man:ranch(3)[ranch(3)]
diff --git a/doc/src/manual/cowboy.stop_listener.asciidoc b/doc/src/manual/cowboy.stop_listener.asciidoc
new file mode 100644
index 0000000..7998189
--- /dev/null
+++ b/doc/src/manual/cowboy.stop_listener.asciidoc
@@ -0,0 +1,55 @@
+= cowboy:stop_listener(3)
+
+== Name
+
+cowboy:stop_listener - Stop the given listener
+
+== Description
+
+[source,erlang]
+----
+stop_listener(Name :: ranch:ref())
+    -> ok | {error, not_found}.
+----
+
+Stop a previously started listener.
+
+Alias of link:man:ranch:stop_listener(3)[ranch:stop_listener(3)].
+
+== Arguments
+
+Name::
+
+The name of the listener to be stopped.
++
+The name of the listener is the first argument given to the
+link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
+link:man:cowboy:start_tls(3)[cowboy:start_tls(3)] or
+link:man:ranch:start_listener(3)[ranch:start_listener(3)] function.
+
+== Return value
+
+The atom `ok` is returned on success.
+
+The `{error, not_found}` tuple is returned when the listener
+does not exist.
+
+== Changelog
+
+* *1.0*: Function introduced.
+
+== Examples
+
+.Stop a listener
+[source,erlang]
+----
+ok = cowboy:stop_listener(example).
+----
+
+== See also
+
+link:man:cowboy(3)[cowboy(3)],
+link:man:cowboy:start_clear(3)[cowboy:start_clear(3)],
+link:man:cowboy:start_tls(3)[cowboy:start_tls(3)],
+link:man:ranch(3)[ranch(3)],
+link:man:ranch:start_listener(3)[ranch:start_listener(3)]