Update the cowboy_router manual

1 files changed, 64 insertions, 27 deletions

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)]