Update docs

1 files changed, 50 insertions, 183 deletions

diff --git a/docs/en/cowboy/2.0/manual/cowboy_handler/index.html b/docs/en/cowboy/2.0/manual/cowboy_handler/index.html
index 73b7738e..604c8f26 100644
--- a/docs/en/cowboy/2.0/manual/cowboy_handler/index.html
+++ b/docs/en/cowboy/2.0/manual/cowboy_handler/index.html
@@ -72,66 +72,57 @@
 <div class="sect1">

 <h2 id="_name">Name</h2>

 <div class="sectionbody">

-<div class="paragraph"><p>cowboy_handler - handler middleware and behaviour</p></div>

+<div class="paragraph"><p>cowboy_handler - Plain HTTP handlers</p></div>

 </div>

 </div>

 <div class="sect1">

 <h2 id="_description">Description</h2>

 <div class="sectionbody">

-<div class="paragraph"><p>The <code>cowboy_handler</code> middleware executes the handler passed

-through the environment values <code>handler</code> and <code>handler_opts</code>,

-and adds the result of this execution to the environment as

-the value <code>result</code>, indicating that the request has been

-handled and received a response.</p></div>

-<div class="paragraph"><p>Environment input:</p></div>

-<div class="dlist"><dl>

-<dt class="hdlist1">

-handler = module()

-</dt>

-<dd>

-<p>

-Handler to be executed.

-</p>

-</dd>

-<dt class="hdlist1">

-handler_opts = any()

-</dt>

-<dd>

-<p>

-Options to be passed to the handler.

-</p>

-</dd>

-</dl></div>

-<div class="paragraph"><p>Environment output:</p></div>

-<div class="dlist"><dl>

-<dt class="hdlist1">

-result = ok

-</dt>

-<dd>

-<p>

-Result of the request.

-</p>

-</dd>

-</dl></div>

-<div class="paragraph"><p>This module also defines the <code>cowboy_handler</code> behaviour that

-defines the basic interface for handlers. All Cowboy handlers

-implement at least the <code>init/2</code> callback, and may implement

-the <code>terminate/3</code> callback optionally.</p></div>

+<div class="paragraph"><p>The <code>cowboy_handler</code> middleware executes the handler selected

+by the router or any other preceding middleware.</p></div>

+<div class="paragraph"><p>This middleware takes the handler module and initial state

+from the <code>handler</code> and <code>handler_opts</code> environment values,

+respectively. On completion, it adds a <code>result</code> value to

+the middleware environment, containing the return value

+of the <code>terminate/3</code> callback (if defined) and <code>ok</code> otherwise.</p></div>

+<div class="paragraph"><p>This module also defines a callback interface for handling

+HTTP requests.</p></div>

 </div>

 </div>

 <div class="sect1">

-<h2 id="_terminate_reasons">Terminate reasons</h2>

+<h2 id="_callbacks">Callbacks</h2>

 <div class="sectionbody">

-<div class="paragraph"><p>The following values may be received as the terminate reason

-in the optional <code>terminate/3</code> callback. Different handler types

-may define additional terminate reasons.</p></div>

+<div class="paragraph"><p>Plain HTTP handlers implement the following interface:</p></div>

+<div class="listingblock">

+<div class="content"><!-- Generator: GNU source-highlight 3.1.8

+by Lorenzo Bettini

+http://www.lorenzobettini.it

+http://www.gnu.org/software/src-highlite -->

+<pre><tt><span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-&gt;</span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}

+

+<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-&gt;</span> <span style="color: #FF6600">ok</span>  <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span>

+

+<span style="color: #009900">Req</span>        <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()

+<span style="color: #009900">State</span>      <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()

+<span style="color: #009900">Reason</span>     <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span>

+            | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>

+<div class="paragraph"><p>These two callbacks are common to all handlers.</p></div>

+<div class="paragraph"><p>Plain HTTP handlers do all their work in the <code>init/2</code>

+callback. Returning <code>ok</code> terminates the handler. If no

+response is sent, Cowboy will send a <code>204 No Content</code>.</p></div>

+<div class="paragraph"><p>The optional <code>terminate/3</code> 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.</p></div>

+<div class="paragraph"><p>The following terminate reasons are defined for plain HTTP

+handlers:</p></div>

 <div class="dlist"><dl>

 <dt class="hdlist1">

 normal

 </dt>

 <dd>

 <p>

-        The connection was closed normally.

+    The connection was closed normally.

 </p>

 </dd>

 <dt class="hdlist1">

@@ -139,157 +130,33 @@ normal
 </dt>

 <dd>

 <p>

-        A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be

-        used to obtain more information about the crash. The function

-        <code>erlang:get_stacktrace/0</code> can also be called to obtain the

-        stacktrace of the process when the crash occurred.

+    A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be

+    used to obtain more information about the crash. The function

+    <code>erlang:get_stacktrace/0</code> can also be called to obtain the

+    stacktrace of the process when the crash occurred.

 </p>

 </dd>

 </dl></div>

 </div>

 </div>

 <div class="sect1">

-<h2 id="_callbacks">Callbacks</h2>

+<h2 id="_exports">Exports</h2>

 <div class="sectionbody">

-<div class="sect2">

-<h3 id="_init_req_opts_8594_ok_req_state_module_req_state_module_req_state_hibernate_timeout_module_req_state_timeout_hibernate">init(Req, Opts) &#8594; {ok, Req, State} | {Module, Req, State} | {Module, Req, State, hibernate | Timeout} | {Module, Req, State, Timeout, hibernate}</h3>

-<div class="dlist"><dl>

-<dt class="hdlist1">

-Req = cowboy_req:req()

-</dt>

-<dd>

-<p>

-The Req object.

-</p>

-</dd>

-<dt class="hdlist1">

-Opts = any()

-</dt>

-<dd>

-<p>

-Handler options.

-</p>

-</dd>

-<dt class="hdlist1">

-State = any()

-</dt>

-<dd>

-<p>

-Handler state.

-</p>

-</dd>

-<dt class="hdlist1">

-Module = module()

-</dt>

-<dd>

-<p>

-Module of the sub-protocol to use.

-</p>

-</dd>

-<dt class="hdlist1">

-Timeout = timeout()

-</dt>

-<dd>

+<div class="paragraph"><p>The following function should be called by modules implementing

+custom handlers to execute the optional terminate callback:</p></div>

+<div class="ulist"><ul>

+<li>

 <p>

-Timeout passed to the sub-protocol, when applicable.

+<a href="../cowboy_handler.terminate">cowboy_handler:terminate(3)</a> - Terminate the handler

 </p>

-</dd>

-</dl></div>

-<div class="paragraph"><p>Process the request.</p></div>

-<div class="paragraph"><p>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.</p></div>

-<div class="paragraph"><p>For basic handlers this is the function where the response

-should be sent. If no response is sent, Cowboy will ensure

-that a <code>204 No Content</code> response is sent.</p></div>

-<div class="paragraph"><p>A crash in this callback will result in <code>terminate/3</code> being

-called if it is defined, with the <code>State</code> argument set to

-the value of <code>Opts</code> originally given to the <code>init/2</code> callback.</p></div>

-</div>

-<div class="sect2">

-<h3 id="_terminate_reason_req_state_8594_ok">terminate(Reason, Req, State) &#8594; ok</h3>

-<div class="dlist"><dl>

-<dt class="hdlist1">

-Reason = any()

-</dt>

-<dd>

-<p>

-Reason for termination.

-</p>

-</dd>

-<dt class="hdlist1">

-Req = cowboy_req:req()

-</dt>

-<dd>

-<p>

-The Req object.

-</p>

-</dd>

-<dt class="hdlist1">

-State = any()

-</dt>

-<dd>

-<p>

-Handler state.

-</p>

-</dd>

-</dl></div>

-<div class="paragraph"><p>Perform any necessary cleanup of the state.</p></div>

-<div class="paragraph"><p>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.</p></div>

-<div class="paragraph"><p>A crash in this callback or an invalid return value will

-result in the closing of the connection and the termination

-of the process.</p></div>

-</div>

+</li>

+</ul></div>

 </div>

 </div>

 <div class="sect1">

-<h2 id="_exports">Exports</h2>

+<h2 id="_see_also">See also</h2>

 <div class="sectionbody">

-<div class="sect2">

-<h3 id="_terminate_reason_req_state_handler_8594_ok">terminate(Reason, Req, State, Handler) &#8594; ok</h3>

-<div class="dlist"><dl>

-<dt class="hdlist1">

-Reason = any()

-</dt>

-<dd>

-<p>

-Reason for termination.

-</p>

-</dd>

-<dt class="hdlist1">

-Req = cowboy_req:req()

-</dt>

-<dd>

-<p>

-The Req object.

-</p>

-</dd>

-<dt class="hdlist1">

-State = any()

-</dt>

-<dd>

-<p>

-Handler state.

-</p>

-</dd>

-<dt class="hdlist1">

-Handler = module()

-</dt>

-<dd>

-<p>

-Handler module.

-</p>

-</dd>

-</dl></div>

-<div class="paragraph"><p>Call the optional <code>terminate/3</code> callback if it exists.</p></div>

-<div class="paragraph"><p>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.</p></div>

-</div>

+<div class="paragraph"><p><a href="../cowboy_app">cowboy(7)</a></p></div>

 </div>

 </div>