From 04247240629f1b9807feca34fde6de89286d4774 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Sun, 25 Sep 2016 17:32:41 +0200
Subject: 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.
---
 doc/src/manual/cowboy.start_tls.asciidoc | 131 +++++++++++++++++++++++++++++++
 1 file changed, 131 insertions(+)
 create mode 100644 doc/src/manual/cowboy.start_tls.asciidoc

(limited to 'doc/src/manual/cowboy.start_tls.asciidoc')

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)]
-- 
cgit v1.2.3