From b13c07932dfe76dfee29a0c5ce1166423faee77d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Fri, 23 Dec 2016 15:33:21 +0100
Subject: Update the cowboy_handler manual

Also fixes a small mistake in cowboy_websocket.
---
 doc/src/manual/cowboy_handler.asciidoc | 114 ++++++++++++---------------------
 1 file changed, 42 insertions(+), 72 deletions(-)

(limited to 'doc/src/manual/cowboy_handler.asciidoc')

diff --git a/doc/src/manual/cowboy_handler.asciidoc b/doc/src/manual/cowboy_handler.asciidoc
index fbbe761..28ac311 100644
--- a/doc/src/manual/cowboy_handler.asciidoc
+++ b/doc/src/manual/cowboy_handler.asciidoc
@@ -2,98 +2,68 @@
 
 == Name
 
-cowboy_handler - handler middleware and behaviour
+cowboy_handler - Plain HTTP handlers
 
 == Description
 
-The `cowboy_handler` middleware executes the handler passed
-through the environment values `handler` and `handler_opts`,
-and adds the result of this execution to the environment as
-the value `result`, indicating that the request has been
-handled and received a response.
+The `cowboy_handler` middleware executes the handler selected
+by the router or any other preceding middleware.
 
-Environment input:
+This middleware takes the handler module and initial state
+from the `handler` and `handler_opts` environment values,
+respectively. On completion, it adds a `result` value to
+the middleware environment, containing the return value
+of the `terminate/3` callback (if defined) and `ok` otherwise.
 
-handler = module():: Handler to be executed.
-handler_opts = any():: Options to be passed to the handler.
-
-Environment output:
-
-result = ok:: Result of the request.
-
-This module also defines the `cowboy_handler` behaviour that
-defines the basic interface for handlers. All Cowboy handlers
-implement at least the `init/2` callback, and may implement
-the `terminate/3` callback optionally.
-
-== Terminate reasons
-
-The following values may be received as the terminate reason
-in the optional `terminate/3` callback. Different handler types
-may define additional terminate reasons.
-
-normal::
-	The connection was closed normally.
-
-{crash, Class, Reason}::
-	A crash occurred in the handler. `Class` and `Reason` can be
-	used to obtain more information about the crash. The function
-	`erlang:get_stacktrace/0` can also be called to obtain the
-	stacktrace of the process when the crash occurred.
+This module also defines a callback interface for handling
+HTTP requests.
 
 == Callbacks
 
-=== init(Req, Opts) -> {ok, Req, State} | {Module, Req, State} | {Module, Req, State, hibernate | Timeout} | {Module, Req, State, Timeout, hibernate}
+Plain HTTP handlers implement the following interface:
 
-Req = cowboy_req:req():: The Req object.
-Opts = any():: Handler options.
-State = any():: Handler state.
-Module = module():: Module of the sub-protocol to use.
-Timeout = timeout():: Timeout passed to the sub-protocol, when applicable.
+[source,erlang]
+----
+init(Req, State) -> {ok, Req, State}
 
-Process the request.
+terminate(Reason, Req, State) -> ok  %% optional
 
-This function can be used to switch to an alternate handler
-type by returning the name of the module to be used, along
-with a few options.
+Req        :: cowboy_req:req()
+State      :: any()
+Reason     :: normal
+            | {crash, error | exit | throw, any()}
+----
 
-For basic handlers this is the function where the response
-should be sent. If no response is sent, Cowboy will ensure
-that a `204 No Content` response is sent.
+These two callbacks are common to all handlers.
 
-A crash in this callback will result in `terminate/3` being
-called if it is defined, with the `State` argument set to
-the value of `Opts` originally given to the `init/2` callback.
+Plain HTTP handlers do all their work in the `init/2`
+callback. Returning `ok` terminates the handler. If no
+response is sent, Cowboy will send a `204 No Content`.
 
-=== terminate(Reason, Req, State) -> ok
+The optional `terminate/3` callback will ultimately be called
+with the reason for the termination of the handler.
+Cowboy will terminate the process right after this. There
+is no need to perform any cleanup in this callback.
 
-Reason = any():: Reason for termination.
-Req = cowboy_req:req():: The Req object.
-State = any():: Handler state.
+The following terminate reasons are defined for plain HTTP
+handlers:
 
-Perform any necessary cleanup of the state.
-
-This callback should release any resource currently in use,
-clear any active timer and reset the process to its original
-state, as it might be reused for future requests sent on the
-same connection. Typical plain HTTP handlers rarely need to
-use it.
+normal::
+    The connection was closed normally.
 
-A crash in this callback or an invalid return value will
-result in the closing of the connection and the termination
-of the process.
+{crash, Class, Reason}::
+    A crash occurred in the handler. `Class` and `Reason` can be
+    used to obtain more information about the crash. The function
+    `erlang:get_stacktrace/0` can also be called to obtain the
+    stacktrace of the process when the crash occurred.
 
 == Exports
 
-=== terminate(Reason, Req, State, Handler) -> ok
+The following function should be called by modules implementing
+custom handlers to execute the optional terminate callback:
 
-Reason = any():: Reason for termination.
-Req = cowboy_req:req():: The Req object.
-State = any():: Handler state.
-Handler = module():: Handler module.
+* link:man:cowboy_handler:terminate(3)[cowboy_handler:terminate(3)] - Terminate the handler
 
-Call the optional `terminate/3` callback if it exists.
+== See also
 
-This function should always be called at the end of the execution
-of a handler, to give it a chance to clean up or perform
-miscellaneous operations.
+link:man:cowboy(7)[cowboy(7)]
-- 
cgit v1.2.3

