16 files changed, 268 insertions, 303 deletions

diff --git a/doc/src/guide/erlang_beginners.ezdoc b/doc/src/guide/erlang_beginners.ezdoc
index f62543f..74d3470 100644
--- a/doc/src/guide/erlang_beginners.ezdoc
+++ b/doc/src/guide/erlang_beginners.ezdoc
@@ -33,8 +33,3 @@ Instead of going into every single details of the language,
 Joe focuses on the central concepts behind Erlang, and shows
 you how they can be used to write a variety of different
 applications.
-
-At the time of writing, the 2nd edition of the book is in beta,
-and includes a few details about upcoming Erlang features that
-cannot be used today. Choose the edition you want, then get
-reading!
diff --git a/doc/src/guide/getting_started.ezdoc b/doc/src/guide/getting_started.ezdoc
index 34f02dc..a959b45 100644
--- a/doc/src/guide/getting_started.ezdoc
+++ b/doc/src/guide/getting_started.ezdoc
@@ -150,15 +150,15 @@ $ make new t=cowboy_http n=hello_handler
 ```
 
 You can then open the `src/hello_handler.erl` file and modify
-the `handle/2` function like this to send a reply.
+the `init/2` function like this to send a reply.
 
 ``` erlang
-handle(Req, State=#state{}) ->
+init(Req, Opts) ->
 	Req2 = cowboy_req:reply(200,
 		[{<<"content-type">>, <<"text/plain">>}],
 		<<"Hello Erlang!">>,
 		Req),
-	{ok, Req2, State}.
+	{ok, Req2, Opts}.
 ```
 
 What the above code does is send a `200 OK` reply, with the
diff --git a/doc/src/guide/handlers.ezdoc b/doc/src/guide/handlers.ezdoc
new file mode 100644
index 0000000..c0fb97e
--- /dev/null
+++ b/doc/src/guide/handlers.ezdoc
@@ -0,0 +1,99 @@
+::: Handlers
+
+Handlers are Erlang modules that handle HTTP requests.
+
+:: Plain HTTP handlers
+
+The most basic handler in Cowboy implements the mandatory
+`init/2` callback, manipulates the request, optionally
+sends a response and then returns.
+
+This callback receives the ^"Req object^req and the options
+defined during the ^"router configuration^routing^.
+
+A handler that does nothing would look like this:
+
+``` erlang
+init(Req, Opts) ->
+    {ok, Req, Opts}.
+```
+
+Despite sending no reply, a `204 No Content` reply will be
+sent to the client, as Cowboy makes sure that a reply is
+sent for every request.
+
+We need to use the Req object for sending a reply.
+
+``` erlang
+init(Req, Opts) ->
+    Req2 = cowboy_req:reply(200, [
+        {<<"content-type">>, <<"text/plain">>}
+    ], <<"Hello World!">>, Req),
+    {ok, Req2, Opts}.
+```
+
+As you can see we return a 3-tuple. `ok` means that the
+handler ran successfully. The Req object is returned as
+it may have been modified as is the case here: replying
+returns a modified Req object that you need to return
+back to Cowboy for proper operations.
+
+The last value of the tuple is a state that will be used
+in every subsequent callbacks to this handler. Plain HTTP
+handlers only have one additional callback, the optional
+`terminate/3`.
+
+:: Other handlers
+
+The `init/2` callback can also be used to inform Cowboy
+that this is a different kind of handler and that Cowboy
+should switch to it. To do this you simply need to return
+the module name of the handler type you want to switch to.
+
+Cowboy comes with three handler types you can switch to:
+^"cowboy_rest^rest_handlers^, ^"cowboy_websocket^ws_handlers^
+and ^"cowboy_loop^loop_handlers^. In addition to those you
+can define your own handler types.
+
+Switching is simple. Instead of returning `ok`, you simply
+return the name of the handler type you want to use. The
+following snippet switches to a Websocket handler:
+
+``` erlang
+init(Req, Opts) ->
+	{cowboy_websocket, Req, Opts}.
+```
+
+You can also switch to your own custom handler type:
+
+``` erlang
+init(Req, Opts) ->
+	{my_handler_type, Req, Opts}.
+```
+
+How to implement a custom handler type is described in the
+^"Sub protocols^sub_protocols chapter.
+
+:: Cleaning up
+
+All handlers coming with Cowboy allow the use of the optional
+`terminate/3` callback.
+
+``` erlang
+terminate(_Reason, Req, State) ->
+    ok.
+```
+
+This callback is strictly reserved for any required cleanup.
+You cannot send a response from this function. There is no
+other return value.
+
+If you used the process dictionary, timers, monitors or may
+be receiving messages, then you can use this function to clean
+them up, as Cowboy might reuse the process for the next
+keep-alive request.
+
+Note that while this function may be called in a Websocket
+handler, it is generally not useful to do any clean up as
+the process terminates immediately after calling this callback
+when using Websocket.
diff --git a/doc/src/guide/http_handlers.ezdoc b/doc/src/guide/http_handlers.ezdoc
deleted file mode 100644
index d846ffe..0000000
--- a/doc/src/guide/http_handlers.ezdoc
+++ /dev/null
@@ -1,132 +0,0 @@
-::: Handling plain HTTP requests
-
-The simplest way to handle a request is by writing a
-plain HTTP handler. It is modeled after Erlang/OTP's
-gen_server behaviour, although simplified, as Cowboy
-will simply call the three callbacks sequentially.
-
-:: Initialization
-
-The first callback, `init/2`, is common to all handlers,
-as it is used to identify the type of handler. Plain
-HTTP handlers just return `http`.
-
-``` erlang
-init(Req, Opts) ->
-    {http, Req, Opts}.
-```
-
-This function receives the options associated with
-this route that you configured previously.
-
-You do not need to validate the options unless they
-are user configured. If they are, and there's a
-configuration error, you may choose to crash. For
-example, this will crash if the required `lang`
-option is not found.
-
-``` erlang
-init(Req, Opts) ->
-    {_, Lang} = lists:keyfind(lang, 1, Opts),
-    {http, Req, Lang}.
-```
-
-If your users are unlikely to figure out the issue
-without explanations, then you should send a more
-meaningful error back to the user. Since we already
-replied to the user, there's no need for us to
-continue with the handler code, so we use the
-`shutdown` return value to stop early.
-
-``` erlang
-init(Req, Opts) ->
-    case lists:keyfind(lang, 1, Opts) of
-        false ->
-            Req2 = cowboy_req:reply(500, [
-                {<<"content-type">>, <<"text/plain">>}
-            ], "Missing option 'lang'.", Req),
-            {shutdown, Req2, undefined};
-        {_, Lang} ->
-            {http, Req, Lang}
-    end.
-```
-
-Once the options have been validated, we can use them
-safely. So we need to pass them onward to the rest of
-the handler. That's what the third element of the return
-tuple, the state, is for.
-
-You may use a state record for this. The record will make
-your handler code clearer and will allow Dialyzer to better
-type check your code.
-
-``` erlang
--record(state, {
-    lang :: en | fr
-    %% More fields here.
-}).
-
-init(Req, Opts) ->
-    {_, Lang} = lists:keyfind(lang, 1, Opts),
-    {http, Req, #state{lang=Lang}}.
-```
-
-You may also use a map. A map is interesting in that you
-do not need to define it beforehand, but is a little less
-efficient and not as well supported by Dialyzer.
-
-``` erlang
-init(Req, Opts) ->
-    {_, Lang} = lists:keyfind(lang, 1, Opts),
-    {http, Req, #{lang => Lang}.
-```
-
-:: Handling the request
-
-The second callback, `handle/2`, is specific to plain HTTP
-handlers. It's where you handle the request.
-
-A handle function that does nothing would look like this:
-
-``` erlang
-handle(Req, State) ->
-    {ok, Req, State}.
-```
-
-There's no other return value. To obtain information about
-the request, or send a response, you would use the Req object
-here. The Req object is documented in its own chapter.
-
-The following handle function will send a fairly original response.
-
-``` erlang
-handle(Req, State) ->
-    Req2 = cowboy_req:reply(200, [
-        {<<"content-type">>, <<"text/plain">>}
-    ], <<"Hello World!">>, Req),
-    {ok, Req2, State}.
-```
-
-:: Cleaning up
-
-The third and last callback, `terminate/3`, is optional.
-
-``` erlang
-terminate(_Reason, Req, State) ->
-    ok.
-```
-
-This callback is strictly reserved for any required cleanup.
-You cannot send a response from this function. There is no
-other return value.
-
-If you used the process dictionary, timers, monitors or may
-be receiving messages, then you can use this function to clean
-them up, as Cowboy might reuse the process for the next
-keep-alive request.
-
-The chances of any of this happening in your handler are pretty
-thin however. The use of the process dictionary is discouraged
-in Erlang code in general. And if you need to use timers, monitors
-or to receive messages, you are better off with a loop handler,
-a different kind of handler meant specifically for this use.
diff --git a/doc/src/guide/index.ezdoc b/doc/src/guide/index.ezdoc
index 300cea8..dbe75ff 100644
--- a/doc/src/guide/index.ezdoc
+++ b/doc/src/guide/index.ezdoc
@@ -1,35 +1,34 @@
 ::: Cowboy User Guide
 
 The Cowboy User Guide explores the modern Web and how to make
-best use of Cowboy for writing powerful web applications.
+best use of Cowboy for writing powerful Web applications.
 
-:: Introducing Cowboy
+:: Rationale
 
-* ^"Introduction^introduction
 * ^"The modern Web^modern_web
 * ^"Erlang and the Web^erlang_web
-* ^"Erlang for beginners^erlang_beginners
+
+:: Introduction
+
+* ^"Introduction^introduction
 * ^"Getting started^getting_started
+* ^"Request overview^overview
+* ^"Erlang for beginners^erlang_beginners
 
-:: HTTP
+:: Configuration
 
-* ^"The life of a request^http_req_life
 * ^"Routing^routing
 * ^"Constraints^constraints
-* ^"Handling plain HTTP requests^http_handlers
+* ^"Static files^static_files
+
+:: Request and response
+
+* ^"Handlers^handlers
 * ^"The Req object^req
 * ^"Reading the request body^req_body
 * ^"Sending a response^resp
 * ^"Using cookies^cookies
-
-:: Multipart
-
-* ^"Introduction to multipart^multipart_intro
-* ^"Multipart requests^multipart_req
-
-:: Static files
-
-* ^"Static handler^static_handlers
+* ^"Multipart^multipart
 
 :: REST
 
@@ -43,14 +42,14 @@ best use of Cowboy for writing powerful web applications.
 * ^"The Websocket protocol^ws_protocol
 * ^"Handling Websocket connections^ws_handlers
 
-:: Server push
+:: Push technology
 
 * ^"Loop handlers^loop_handlers
 
-:: Pluggable interface
+:: Extensions
 
 * ^"Middlewares^middlewares
-* ^"Protocol upgrades^upgrade_protocol
+* ^"Sub protocols^sub_protocols
 * ^"Hooks^hooks
 
 :: Internals
diff --git a/doc/src/guide/introduction.ezdoc b/doc/src/guide/introduction.ezdoc
index 18345df..e1d2e60 100644
--- a/doc/src/guide/introduction.ezdoc
+++ b/doc/src/guide/introduction.ezdoc
@@ -16,9 +16,7 @@ features both a Function Reference and a User Guide.
 
 :: Prerequisites
 
-No Erlang knowledge is required for reading this guide. The reader will
-be introduced to Erlang concepts and redirected to reference material
-whenever necessary.
+Beginner Erlang knowledge is recommended for reading this guide.
 
 Knowledge of the HTTP protocol is recommended but not required, as it
 will be detailed throughout the guide.
@@ -32,12 +30,15 @@ guarantee that the experience will be safe and smooth. You are advised
 to perform the necessary testing and security audits prior to deploying
 on other platforms.
 
-Cowboy is developed for Erlang/OTP R16B01, R16B02, R16B03-1, 17.0 and
-17.1.2.
+Cowboy is developed for Erlang/OTP 17.0, 17.1.2 and 17.3. By the time
+this branch gets released the target version will probably be 18.0 and
+above.
 
 Cowboy may be compiled on other Erlang versions with small source code
 modifications but there is no guarantee that it will work as expected.
 
+Cowboy uses the maps data type which was introduced in Erlang 17.0.
+
 :: Versioning
 
 Cowboy uses ^"Semantic Versioning 2.0.0^http://semver.org/^.
diff --git a/doc/src/guide/loop_handlers.ezdoc b/doc/src/guide/loop_handlers.ezdoc
index 445854c..8da2805 100644
--- a/doc/src/guide/loop_handlers.ezdoc
+++ b/doc/src/guide/loop_handlers.ezdoc
@@ -8,7 +8,7 @@ a response.
 Loop handlers are used for requests where a response might not
 be immediately available, but where you would like to keep the
 connection open for a while in case the response arrives. The
-most known example of such practice is known as long-polling.
+most known example of such practice is known as long polling.
 
 Loop handlers can also be used for requests where a response is
 partially available and you need to stream the response body
@@ -21,12 +21,12 @@ and allow using built-in features like hibernation and timeouts.
 
 Loop handlers essentially wait for one or more Erlang messages
 and feed these messages to the `info/3` callback. It also features
-the `init/3` and `terminate/3` callbacks which work the same as
+the `init/2` and `terminate/3` callbacks which work the same as
 for plain HTTP handlers.
 
 :: Initialization
 
-The `init/3` function must return a `loop` tuple to enable
+The `init/2` function must return a `cowboy_loop` tuple to enable
 loop handler behavior. This tuple may optionally contain
 a timeout value and/or the atom `hibernate` to make the
 process enter hibernation until a message is received.
@@ -35,7 +35,7 @@ This snippet enables the loop handler.
 
 ``` erlang
 init(Req, Opts) ->
-    {long_polling, Req, Opts}.
+    {cowboy_loop, Req, Opts}.
 ```
 
 However it is largely recommended that you set a timeout
@@ -44,7 +44,7 @@ also makes the process hibernate.
 
 ``` erlang
 init(Req, Opts) ->
-    {long_polling, Req, Opts, 30000, hibernate}.
+    {cowboy_loop, Req, Opts, 30000, hibernate}.
 ```
 
 :: Receive loop
@@ -61,9 +61,9 @@ message otherwise.
 ``` erlang
 info({reply, Body}, Req, State) ->
     Req2 = cowboy_req:reply(200, [], Body, Req),
-    {ok, Req2, State};
+    {shutdown, Req2, State};
 info(_Msg, Req, State) ->
-    {loop, Req, State, hibernate}.
+    {ok, Req, State, hibernate}.
 ```
 
 Do note that the `reply` tuple here may be any message
@@ -76,17 +76,17 @@ return a tuple indicating if more messages are to be expected.
 The callback may also choose to do nothing at all and just
 skip the message received.
 
-If a reply is sent, then the `ok` tuple should be returned.
+If a reply is sent, then the `shutdown` tuple should be returned.
 This will instruct Cowboy to end the request.
 
-Otherwise a `loop` tuple should be returned.
+Otherwise an `ok` tuple should be returned.
 
 :: Streaming loop
 
 Another common case well suited for loop handlers is
 streaming data received in the form of Erlang messages.
 This can be done by initiating a chunked reply in the
-`init/3` callback and then using `cowboy_req:chunk/2`
+`init/2` callback and then using `cowboy_req:chunk/2`
 every time a message is received.
 
 The following snippet does exactly that. As you can see
@@ -96,15 +96,15 @@ and the loop is stopped by sending an `eof` message.
 ``` erlang
 init(Req, Opts) ->
 	Req2 = cowboy_req:chunked_reply(200, [], Req),
-    {long_polling, Req2, Opts}.
+    {cowboy_loop, Req2, Opts}.
 
 info(eof, Req, State) ->
-    {ok, Req, State};
+    {shutdown, Req, State};
 info({chunk, Chunk}, Req, State) ->
     cowboy_req:chunk(Chunk, Req),
-    {loop, Req, State};
+    {ok, Req, State};
 info(_Msg, Req, State) ->
-    {loop, Req, State}.
+    {ok, Req, State}.
 ```
 
 :: Cleaning up
diff --git a/doc/src/guide/multipart_req.ezdoc b/doc/src/guide/multipart.ezdoc
index 21762f6..d0b2e40 100644
--- a/doc/src/guide/multipart_req.ezdoc
+++ b/doc/src/guide/multipart.ezdoc
@@ -1,11 +1,60 @@
 ::: Multipart requests
 
+Multipart originates from MIME, an Internet standard that
+extends the format of emails. Multipart messages are a
+container for parts of any content-type.
+
+For example, a multipart message may have a part
+containing text and a second part containing an
+image. This is what allows you to attach files
+to emails.
+
+In the context of HTTP, multipart is most often used
+with the `multipart/form-data` content-type. This is
+the content-type you have to use when you want browsers
+to be allowed to upload files through HTML forms.
+
+Multipart is of course not required for uploading
+files, it is only required when you want to do so
+through HTML forms.
+
 You can read and parse multipart messages using the
 Req object directly.
 
 Cowboy defines two functions that allows you to get
 information about each part and read their contents.
 
+:: Structure
+
+A multipart message is a list of parts. Parts may
+contain either a multipart message or a non-multipart
+content-type. This allows parts to be arranged in a
+tree structure, although this is a rare case as far
+as the Web is concerned.
+
+:: Form-data
+
+In the normal case, when a form is submitted, the
+browser will use the `application/x-www-form-urlencoded`
+content-type. This type is just a list of keys and
+values and is therefore not fit for uploading files.
+
+That's where the `multipart/form-data` content-type
+comes in. When the form is configured to use this
+content-type, the browser will use one part of the
+message for each form field. This means that a file
+input field will be sent in its own part, but the
+same applies to all other kinds of fields.
+
+A form with a text input, a file input and a select
+choice box will result in a multipart message with
+three parts, one for each field.
+
+The browser does its best to determine the content-type
+of the files it sends this way, but you should not
+rely on it for determining the contents of the file.
+Proper investigation of the contents is recommended.
+
 :: Checking the content-type
 
 While there is a variety of multipart messages, the
diff --git a/doc/src/guide/multipart_intro.ezdoc b/doc/src/guide/multipart_intro.ezdoc
deleted file mode 100644
index b9a7fa9..0000000
--- a/doc/src/guide/multipart_intro.ezdoc
+++ /dev/null
@@ -1,50 +0,0 @@
-::: Introduction to multipart
-
-Multipart originates from MIME, an Internet standard that
-extends the format of emails. Multipart messages are a
-container for parts of any content-type.
-
-For example, a multipart message may have a part
-containing text and a second part containing an
-image. This is what allows you to attach files
-to emails.
-
-In the context of HTTP, multipart is most often used
-with the `multipart/form-data` content-type. This is
-the content-type you have to use when you want browsers
-to be allowed to upload files through HTML forms.
-
-Multipart is of course not required for uploading
-files, it is only required when you want to do so
-through HTML forms.
-
-:: Structure
-
-A multipart message is a list of parts. Parts may
-contain either a multipart message or a non-multipart
-content-type. This allows parts to be arranged in a
-tree structure, although this is a rare case as far
-as the Web is concerned.
-
-:: Form-data
-
-In the normal case, when a form is submitted, the
-browser will use the `application/x-www-form-urlencoded`
-content-type. This type is just a list of keys and
-values and is therefore not fit for uploading files.
-
-That's where the `multipart/form-data` content-type
-comes in. When the form is configured to use this
-content-type, the browser will use one part of the
-message for each form field. This means that a file
-input field will be sent in its own part, but the
-same applies to all other kinds of fields.
-
-A form with a text input, a file input and a select
-choice box will result in a multipart message with
-three parts, one for each field.
-
-The browser does its best to determine the content-type
-of the files it sends this way, but you should not
-rely on it for determining the contents of the file.
-Proper investigation of the contents is recommended.
diff --git a/doc/src/guide/http_req_life.ezdoc b/doc/src/guide/overview.ezdoc
index ffe5dfa..725ae4e 100644
--- a/doc/src/guide/http_req_life.ezdoc
+++ b/doc/src/guide/overview.ezdoc
@@ -1,4 +1,4 @@
-::: The life of a request
+::: Request overview
 
 This chapter explains the different steps a request
 goes through until a response is sent, along with
diff --git a/doc/src/guide/rest_handlers.ezdoc b/doc/src/guide/rest_handlers.ezdoc
index 294392a..8cdd12e 100644
--- a/doc/src/guide/rest_handlers.ezdoc
+++ b/doc/src/guide/rest_handlers.ezdoc
@@ -1,20 +1,20 @@
 ::: REST handlers
 
-REST is implemented in Cowboy as a protocol upgrade. Once upgraded,
-the request is handled as a state machine with many optional callbacks
+REST is implemented in Cowboy as a sub protocol. The request
+is handled as a state machine with many optional callbacks
 describing the resource and modifying the machine's behavior.
 
-The REST handler is the recommended way to handle requests.
+The REST handler is the recommended way to handle HTTP requests.
 
 :: Initialization
 
 First, the `init/2` callback is called. This callback is common
 to all handlers. To use REST for the current request, this function
-must return a `rest` tuple.
+must return a `cowboy_rest` tuple.
 
 ``` erlang
 init(Req, Opts) ->
-    {rest, Req, Opts}.
+    {cowboy_rest, Req, Opts}.
 ```
 
 Cowboy will then switch to the REST protocol and start executing
diff --git a/doc/src/guide/static_handlers.ezdoc b/doc/src/guide/static_files.ezdoc
index f5eaac3..5a289d0 100644
--- a/doc/src/guide/static_handlers.ezdoc
+++ b/doc/src/guide/static_files.ezdoc
@@ -1,8 +1,9 @@
-::: Static handler
+::: Static files
 
-The static handler is a built-in REST handler for serving files.
-It is available as a convenience and provides a quick solution
-for serving files during development.
+Cowboy comes with a special handler built as a REST handler
+and designed specifically for serving static files. It is
+provided as a convenience and provides a quick solution for
+serving files during development.
 
 For systems in production, consider using one of the many
 Content Distribution Network (CDN) available on the market,
diff --git a/doc/src/guide/sub_protocols.ezdoc b/doc/src/guide/sub_protocols.ezdoc
new file mode 100644
index 0000000..d34f21e
--- /dev/null
+++ b/doc/src/guide/sub_protocols.ezdoc
@@ -0,0 +1,64 @@
+::: Sub protocols
+
+Sub protocols are used for creating new types of handlers that
+provide extra functionality in a reusable way. Cowboy uses this
+mechanism to provide its loop, REST and Websocket handlers.
+
+This chapter will explain how to create your own sub protocols
+and handler types.
+
+:: Usage
+
+To switch to a sub protocol, the `init/2` callback must return
+the name of the sub protocol module. Everything past this point
+is handled by the sub protocol.
+
+``` erlang
+init(Req, Opts) ->
+	{cowboy_websocket, Req, Opts}.
+```
+
+The return value may also have a `Timeout` value and/or the
+atom `hibernate`. These options are useful for long living
+connections. When they are not provided, the timeout value
+defaults to `infinity` and the hibernate value to `run`.
+
+The following snippet switches to the `my_protocol` sub
+protocol, sets the timeout value to 5 seconds and enables
+hibernation:
+
+``` erlang
+init(Req, Opts) ->
+	{my_protocol, Req, Opts, 5000, hibernate}.
+```
+
+If a sub protocol does not make use of these options, it should
+crash if it receives anything other than the default values.
+
+:: Upgrade
+
+After the `init/2` function returns, Cowboy will then call the
+`upgrade/6` function. This is the only callback defined by the
+`cowboy_sub_protocol` behavior.
+
+The function is named `upgrade` because it mimics the mechanism
+of HTTP protocol upgrades. For some sub protocols, like Websocket,
+an actual upgrade is performed. For others, like REST, this is
+only an upgrade at Cowboy's level and the client has nothing to
+do about it.
+
+The upgrade callback receives the Req object, the middleware
+environment, the handler and its options, and the aforementioned
+timeout and hibernate values.
+
+``` erlang
+upgrade(Req, Env, Handler, HandlerOpts, Timeout, Hibernate) ->
+	%% Sub protocol code here.
+```
+
+This callback is expected to behave like a middleware and to
+return an updated environment and Req object.
+
+Sub protocols are expected to call the `cowboy_handler:terminate/4`
+function when they terminate. This function will make sure that
+the optional `terminate/3` callback is called, if present.
diff --git a/doc/src/guide/upgrade_protocol.ezdoc b/doc/src/guide/upgrade_protocol.ezdoc
deleted file mode 100644
index ad2d25a..0000000
--- a/doc/src/guide/upgrade_protocol.ezdoc
+++ /dev/null
@@ -1,61 +0,0 @@
-::: Protocol upgrades
-
-Cowboy features many different handlers, each for different purposes.
-All handlers have a common entry point: the `init/2` function.
-This function returns the name of the protocol that will be
-used for processing the request, along with various options.
-
-Cowboy defines four built-in handler types. Three of them are
-implemented as sub protocols. More can be implemented by
-writing a custom sub protocol.
-
-The following table lists the built-in handler types.
-
-||	Alias			Module				Description
-|
-|	http			-					Plain HTTP handler
-|	long_polling	cowboy_long_polling	Long-polling handler
-|	rest			cowboy_rest			REST handler
-|	ws				cowboy_websocket	Websocket handler
-
-Both the alias or the module name can be used to specify the
-kind of handler. In addition, a user-defined module name can
-be used.
-
-``` erlang
-init(Req, Opts) ->
-	{my_protocol, Req, Opts}.
-```
-
-The `init/2` function can also return some extra options for
-handlers that are meant to be long running, for example the
-`long_polling` and `ws` handler types. These options can also
-be passed on to custom sub protocols. For example the following
-`init/2` function defines both a timeout value and enables
-process hibernation:
-
-``` erlang
-init(Req, Opts) ->
-	{my_protocol, Req, Opts, 5000, hibernate}.
-```
-
-It is up to the sub protocol to implement these (or reject
-them if they are not supported).
-
-The `cowboy_sub_protocol` behavior only requires one callback,
-`upgrade/6`. It receives the Req object, the middleware environment,
-the handler and options for this request, and the timeout and
-hibernate values. The default timeout value is `infinity` and
-the default hibernate value is `run`.
-
-``` erlang
-upgrade(Req, Env, Handler, HandlerOpts, Timeout, Hibernate) ->
-    %% ...
-```
-
-This callback is expected to behave like a middleware. Please
-see the corresponding chapter for more information.
-
-Sub protocols are expected to call the `cowboy_handler:terminate/5`
-function when they terminate. This function will make sure that
-the optional `terminate/3` callback will be called, if present.
diff --git a/doc/src/guide/ws_handlers.ezdoc b/doc/src/guide/ws_handlers.ezdoc
index 893624b..cb30511 100644
--- a/doc/src/guide/ws_handlers.ezdoc
+++ b/doc/src/guide/ws_handlers.ezdoc
@@ -17,7 +17,7 @@ must return a `ws` tuple.
 
 ``` erlang
 init(Req, Opts) ->
-	{ws, Req, Opts}.
+	{cowboy_websocket, Req, Opts}.
 ```
 
 Upon receiving this tuple, Cowboy will switch to the code
@@ -61,7 +61,7 @@ or enabling timers.
 init(Req, _Opts) ->
 	self() ! post_init,
 	%% Register process here...
-	{ws, Req, #state{}}.
+	{cowboy_websocket, Req, #state{}}.
 
 websocket_info(post_init, Req, State) ->
 	%% Perform post_init initialization here...
@@ -161,7 +161,7 @@ A good timeout value is 60 seconds.
 
 ``` erlang
 init(Req, _Opts) ->
-	{ws, Req, #state{}, 60000}.
+	{cowboy_websocket, Req, #state{}, 60000}.
 ```
 
 This value cannot be changed once it is set. It defaults to
diff --git a/doc/src/guide/ws_protocol.ezdoc b/doc/src/guide/ws_protocol.ezdoc
index 15aea2c..d283ae3 100644
--- a/doc/src/guide/ws_protocol.ezdoc
+++ b/doc/src/guide/ws_protocol.ezdoc
@@ -25,7 +25,7 @@ excluding the initial flawed draft sometimes known as
 :: Implementation
 
 Cowboy implements Websocket as a protocol upgrade. Once the
-upgrade is performed from the `init/3` callback, Cowboy
+upgrade is performed from the `init/2` callback, Cowboy
 switches to Websocket. Please consult the next chapter for
 more information on initiating and handling Websocket
 connections.