6 files changed, 125 insertions, 31 deletions
diff --git a/doc/src/manual/cowboy_req.binding.asciidoc b/doc/src/manual/cowboy_req.binding.asciidoc
index 4e27f31..02f8209 100644
--- a/doc/src/manual/cowboy_req.binding.asciidoc
+++ b/doc/src/manual/cowboy_req.binding.asciidoc
@@ -64,4 +64,5 @@ Branch = cowboy_req:binding(branch, Req, <<"master">>)
 link:man:cowboy_req(3)[cowboy_req(3)],
 link:man:cowboy_req:bindings(3)[cowboy_req:bindings(3)],
 link:man:cowboy_req:host_info(3)[cowboy_req:host_info(3)],
-link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)]
+link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)],
+link:man:cowboy_router(3)[cowboy_router(3)]
diff --git a/doc/src/manual/cowboy_req.bindings.asciidoc b/doc/src/manual/cowboy_req.bindings.asciidoc
index 3e89859..3099366 100644
--- a/doc/src/manual/cowboy_req.bindings.asciidoc
+++ b/doc/src/manual/cowboy_req.bindings.asciidoc
@@ -43,4 +43,5 @@ Bindings = cowboy_req:bindings(Req).
 link:man:cowboy_req(3)[cowboy_req(3)],
 link:man:cowboy_req:binding(3)[cowboy_req:binding(3)],
 link:man:cowboy_req:host_info(3)[cowboy_req:host_info(3)],
-link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)]
+link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)],
+link:man:cowboy_router(3)[cowboy_router(3)]
diff --git a/doc/src/manual/cowboy_req.host_info.asciidoc b/doc/src/manual/cowboy_req.host_info.asciidoc
index 77a4c11..ed613c6 100644
--- a/doc/src/manual/cowboy_req.host_info.asciidoc
+++ b/doc/src/manual/cowboy_req.host_info.asciidoc
@@ -45,4 +45,5 @@ HostInfo = cowboy_req:host_info(Req).
 link:man:cowboy_req(3)[cowboy_req(3)],
 link:man:cowboy_req:binding(3)[cowboy_req:binding(3)],
 link:man:cowboy_req:bindings(3)[cowboy_req:bindings(3)],
-link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)]
+link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)],
+link:man:cowboy_router(3)[cowboy_router(3)]
diff --git a/doc/src/manual/cowboy_req.path_info.asciidoc b/doc/src/manual/cowboy_req.path_info.asciidoc
index d114640..d6d7541 100644
--- a/doc/src/manual/cowboy_req.path_info.asciidoc
+++ b/doc/src/manual/cowboy_req.path_info.asciidoc
@@ -45,4 +45,5 @@ PathInfo = cowboy_req:path_info(Req).
 link:man:cowboy_req(3)[cowboy_req(3)],
 link:man:cowboy_req:binding(3)[cowboy_req:binding(3)],
 link:man:cowboy_req:bindings(3)[cowboy_req:bindings(3)],
-link:man:cowboy_req:host_info(3)[cowboy_req:host_info(3)]
+link:man:cowboy_req:host_info(3)[cowboy_req:host_info(3)],
+link:man:cowboy_router(3)[cowboy_router(3)]
diff --git a/doc/src/manual/cowboy_router.asciidoc b/doc/src/manual/cowboy_router.asciidoc
index 9142930..a830618 100644
--- a/doc/src/manual/cowboy_router.asciidoc
+++ b/doc/src/manual/cowboy_router.asciidoc
@@ -2,55 +2,92 @@
 
 == Name
 
-cowboy_router - router middleware
+cowboy_router - Router middleware
 
 == Description
 
 The `cowboy_router` middleware maps the requested host and
 path to the handler to be used for processing the request.
-It uses the dispatch rules compiled from the routes given
-to the `compile/1` function for this purpose. It adds the
-handler name and options to the environment as the values
-`handler` and `handler_opts` respectively.
 
-=== Environment input
+The router takes the `dispatch` rules as input from the
+middleware environment. Dispatch rules are generated by
+calling the
+link:man:cowboy_router:compile(3)[cowboy_router:compile(3)]
+function.
 
-dispatch = dispatch_rules():: Dispatch table.
+When a route matches, the router sets the `handler` and
+`handler_opts` middleware environment values containing
+the handler module and initial state, respectively.
 
-=== Environment output
+The router will stop execution when no route matches.
+It will send a 400 response if no host was found, and
+a 404 response otherwise.
 
-handler = module():: Handler module.
-handler_opts = any():: Handler options.
+== Exports
+
+* link:man:cowboy_router:compile(3)[cowboy_router:compile(3)] - Compile routes to the resources
 
 == Types
 
-=== bindings() = [{atom(), binary()}]
+=== bindings()
 
-List of bindings found during routing.
+[source,erlang]
+----
+bindings() :: [{atom(), binary()}]
+----
 
-=== dispatch_rules() - opaque to the user
+Bindings found during routing.
 
-Rules for dispatching request used by Cowboy.
+=== dispatch_rules()
 
-=== routes() = [{Host, Paths} | {Host, cowboy:fields(), Paths}]
+Opaque type containing the compiled routes.
 
-With types:
+=== routes()
 
-* Host = Path = '_' | iodata()
-* Paths = [{Path, Handler, Opts} | {Path, cowboy:fields(), Handler, HandlerOpts}]
-* Handler = module()
-* HandlerOpts = any()
+[source,erlang]
+----
+routes() = [
+    {Host, PathList} |
+    {Host, Fields, PathList}
+]
 
-Human readable list of routes mapping hosts and paths to handlers.
+PathList :: [
+    {Path, Handler, InitialState} |
+    {Path, Fields, Handler, InitialState}
+]
 
-The syntax for routes is defined in the user guide.
+Host         :: '_' | iodata()
+Path         :: '_' | iodata()
+Fields       :: cowboy:fields()
+Handler      :: module()
+InitialState :: any()
+----
 
-=== tokens() = [binary()]
+Human readable list of routes to handlers.
 
-List of host_info and path_info tokens found during routing.
+Cowboy uses this list to map hosts and paths, optionally
+augmented with constraints applied to the bindings, to
+handler modules.
 
-== Exports
+The syntax for routes is currently defined in the user guide.
+
+// @todo The syntax should probably be in this module,
+// and the user guide show more practical examples.
+
+=== tokens()
+
+[source,erlang]
+----
+tokens() :: [binary()]
+----
+
+List of `host_info` and `path_info` tokens that were found
+using the `...` syntax.
 
-=== compile(routes()) -> dispatch_rules()
+== See also
 
-Compile the routes for use by Cowboy.
+link:man:cowboy(7)[cowboy(7)],
+link:man:cowboy_req:binding(3)[cowboy_req:binding(3)],
+link:man:cowboy_req:bindings(3)[cowboy_req:bindings(3)],
+link:man:cowboy_req:host_info(3)[cowboy_req:host_info(3)],
+link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)]
diff --git a/doc/src/manual/cowboy_router.compile.asciidoc b/doc/src/manual/cowboy_router.compile.asciidoc
new file mode 100644
index 0000000..ab4eddc
--- /dev/null
+++ b/doc/src/manual/cowboy_router.compile.asciidoc
@@ -0,0 +1,53 @@
+= cowboy_router:compile(3)
+
+== Name
+
+cowboy_router:compile - Compile routes to the resources
+
+== Description
+
+[source,erlang]
+----
+compile(cowboy_router:routes()) -> cowboy_router:dispatch_rules()
+----
+
+Compile routes to the resources.
+
+Takes a human readable list of routes and transforms it
+into a form more efficient to process.
+
+== Arguments
+
+Routes::
+
+Human readable list of routes.
+
+== Return value
+
+An opaque dispatch rules value is returned. This value
+must be given to Cowboy as a middleware environment value.
+
+== Changelog
+
+* *1.0*: Function introduced.
+
+== Examples
+
+.Compile routes and start a listener
+[source,erlang]
+----
+Dispatch = cowboy_router:compile([
+    {'_', [
+        {"/", toppage_h, []},
+        {"/[...], cowboy_static, {priv_dir, my_example_app, ""}}
+    ]}
+]),
+
+{ok, _} = cowboy:start_clear(example, 100, [{port, 8080}], #{
+    env => #{dispatch => Dispatch}
+}).
+----
+
+== See also
+
+link:man:cowboy_router(3)[cowboy_router(3)]