Remove cowboy_sub_protocol from the documentation

This will be reintroduced in a future release once the
interface stabilizes. For the time being it will be an
internal module only.

1 files changed, 0 insertions, 73 deletions

diff --git a/doc/src/guide/sub_protocols.asciidoc b/doc/src/guide/sub_protocols.asciidoc
deleted file mode 100644
index 83fa975..0000000
--- a/doc/src/guide/sub_protocols.asciidoc
+++ /dev/null
@@ -1,73 +0,0 @@
-[[sub_protocols]]
-== 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.
-
-[source,erlang]
-----
-init(Req, State) ->
-    {cowboy_websocket, Req, State}.
-----
-
-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:
-
-[source,erlang]
-----
-init(Req, State) ->
-    {my_protocol, Req, State, #{
-        timeout => 5000,
-        compress => true}}.
-----
-
-Sub protocols should ignore unknown options so as to not waste
-resources doing unnecessary validation.
-
-=== Upgrade
-
-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,
-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 state, and for `upgrade/5`
-also the aformentioned options.
-
-[source,erlang]
-----
-upgrade(Req, Env, Handler, State) ->
-    %% Sub protocol code here.
-
-upgrade(Req, Env, Handler, State, Opts) ->
-    %% Sub protocol code here.
-----
-
-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`
-function when they terminate. This function will make sure that
-the optional `terminate/3` callback is called, if present.