Update the cowboy_handler manual

Also fixes a small mistake in cowboy_websocket.

doc/src/manual/cowboy_handler.asciidoc

@@ -2,35 +2,51 @@
 
 == Name
 
-cowboy_handler - handler middleware and behaviour
+cowboy_handler - Plain HTTP handlers
 
 == Description
 
-The `cowboy_handler` middleware executes the handler passed
+The `cowboy_handler` middleware executes the handler selected
-through the environment values `handler` and `handler_opts`,
+by the router or any other preceding middleware.
-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.
 
-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.
+This module also defines a callback interface for handling
-handler_opts = any():: Options to be passed to the handler.
+HTTP requests.
 
-Environment output:
+== Callbacks
 
-result = ok:: Result of the request.
+Plain HTTP handlers implement the following interface:
 
-This module also defines the `cowboy_handler` behaviour that
+[source,erlang]
-defines the basic interface for handlers. All Cowboy handlers
+----
-implement at least the `init/2` callback, and may implement
+init(Req, State) -> {ok, Req, State}
-the `terminate/3` callback optionally.
 
-== Terminate reasons
+terminate(Reason, Req, State) -> ok  %% optional
 
-The following values may be received as the terminate reason
+Req        :: cowboy_req:req()
-in the optional `terminate/3` callback. Different handler types
+State      :: any()
-may define additional terminate reasons.
+Reason     :: normal
+            | {crash, error | exit | throw, any()}
+----
+
+These two callbacks are common to all handlers.
+
+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`.
+
+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.
+
+The following terminate reasons are defined for plain HTTP
+handlers:
 
 normal::
     The connection was closed normally.
@@ -41,59 +57,13 @@ normal::
     `erlang:get_stacktrace/0` can also be called to obtain the
     stacktrace of the process when the crash occurred.
 
-== Callbacks
-
-=== init(Req, Opts) -> {ok, Req, State} | {Module, Req, State} | {Module, Req, State, hibernate | Timeout} | {Module, Req, State, Timeout, hibernate}
-
-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.
-
-Process the request.
-
-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.
-
-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.
-
-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.
-
-=== terminate(Reason, Req, State) -> ok
-
-Reason = any():: Reason for termination.
-Req = cowboy_req:req():: The Req object.
-State = any():: Handler state.
-
-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.
-
-A crash in this callback or an invalid return value will
-result in the closing of the connection and the termination
-of the process.
-
 == 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.
+* link:man:cowboy_handler:terminate(3)[cowboy_handler:terminate(3)] - Terminate the handler
-Req = cowboy_req:req():: The Req object.
-State = any():: Handler state.
-Handler = module():: Handler module.
 
-Call the optional `terminate/3` callback if it exists.
+== See also
 
-This function should always be called at the end of the execution
+link:man:cowboy(7)[cowboy(7)]
-of a handler, to give it a chance to clean up or perform
-miscellaneous operations.

doc/src/manual/cowboy_handler.terminate.asciidoc

@@ -0,0 +1,64 @@
+= cowboy_handler:terminate(3)
+
+== Name
+
+cowboy_handler:terminate - Terminate the handler
+
+== Description
+
+[source,erlang]
+----
+terminate(Reason, Req | undefined, State, Handler) -> ok
+
+Reason  :: any()
+Req     :: cowboy_req:req()
+State   :: any()
+Handler :: module()
+----
+
+Call the optional terminate callback if it is defined.
+
+Make sure to use this function at the end of the execution
+of modules that implement custom handler behaviors.
+
+== Arguments
+
+Reason::
+
+Reason for termination.
+
+Req::
+
+The Req object.
++
+It is possible to pass `undefined` if the handler has no concept
+of requests/responses and discarded the Req object before calling
+this function.
+
+State::
+
+Handler state.
+
+Handler::
+
+Handler module.
+
+== Return value
+
+The atom `ok` is always returned. It can be safely ignored.
+
+== Changelog
+
+* *2.0*: Function introduced.
+
+== Examples
+
+.Terminate a handler normally
+[source,erlang]
+----
+cowboy_handler:terminate(normal, Req, State, Handler).
+----
+
+== See also
+
+link:man:cowboy_handler(3)[cowboy_handler(3)]

doc/src/manual/cowboy_websocket.asciidoc

@@ -52,7 +52,7 @@ websocket_init(State)            -> CallResult  %% optional
 websocket_handle(InFrame, State) -> CallResult
 websocket_info(Info, State)      -> CallResult
 
-terminate(Reason, undefined, State) -> any()    %% optional
+terminate(Reason, undefined, State) -> ok       %% optional
 
 Req        :: cowboy_req:req()
 State      :: any()