1 files changed, 19 insertions, 16 deletions
diff --git a/doc/src/guide/sub_protocols.asciidoc b/doc/src/guide/sub_protocols.asciidoc
index 2ab96bc..83fa975 100644
--- a/doc/src/guide/sub_protocols.asciidoc
+++ b/doc/src/guide/sub_protocols.asciidoc
@@ -20,31 +20,31 @@ init(Req, State) ->
     {cowboy_websocket, Req, State}.
 ----
 
-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 returned tuple may also have a fourth element containing
+options for the sub protocol. No option is universal. While
+it will usually be a map of options, it doesn't have to be.
+For example loop handlers accept the atom `hibernate`.
 
 The following snippet switches to the `my_protocol` sub
 protocol, sets the timeout value to 5 seconds and enables
 hibernation:
 
-// @todo Yeah maybe what we really need is an Opts map.
-
 [source,erlang]
 ----
 init(Req, State) ->
-    {my_protocol, Req, State, 5000, hibernate}.
+    {my_protocol, Req, State, #{
+        timeout => 5000,
+        compress => true}}.
 ----
 
-If a sub protocol does not make use of these options, it should
-crash if it receives anything other than the default values.
+Sub protocols should ignore unknown options so as to not waste
+resources doing unnecessary validation.
 
 === 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.
+After the `init/2` function returns, Cowboy will call either
+the `upgrade/4` or the `upgrade/5` function. The former is called
+when no options were given; the latter when they were given.
 
 The function is named `upgrade` because it mimics the mechanism
 of HTTP protocol upgrades. For some sub protocols, like Websocket,
@@ -53,16 +53,19 @@ 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.
+environment, the handler and its state, and for `upgrade/5`
+also the aformentioned options.
 
 [source,erlang]
 ----
-upgrade(Req, Env, Handler, HandlerOpts, Timeout, Hibernate) ->
+upgrade(Req, Env, Handler, State) ->
+    %% Sub protocol code here.
+
+upgrade(Req, Env, Handler, State, Opts) ->
     %% Sub protocol code here.
 ----
 
-This callback is expected to behave like a middleware and to
+These callbacks are expected to behave like middlewares and to
 return an updated environment and Req object.
 
 Sub protocols are expected to call the `cowboy_handler:terminate/4`