Improve handler interface and documentation

This change simplifies a little more the sub protocols mechanism.
Aliases have been removed. The renaming of loop handlers as long
polling handlers has been reverted.

Plain HTTP handlers now simply do their work in the init/2
callback. There is no specific code for them.

Loop handlers now follow the same return value as Websocket,
they use ok to continue and shutdown to stop.

Terminate reasons for all handler types have been documented.
The terminate callback is now appropriately called in all cases
(or should be).

Behaviors for all handler types have been moved in the module
that implement them. This means that cowboy_handler replaces
the cowboy_http_handler behavior, and similarly cowboy_loop
replaces cowboy_loop_handler, cowboy_websocket replaces
cowboy_websocket_handler. Finally cowboy_rest now has the
start of a behavior in it and will have the full list of
optional callbacks defined once Erlang 18.0 gets released.

The guide has been reorganized and should be easier to follow.

1 files changed, 131 insertions, 2 deletions

diff --git a/doc/src/manual/cowboy_websocket.ezdoc b/doc/src/manual/cowboy_websocket.ezdoc
index 59a6248..889ddd7 100644
--- a/doc/src/manual/cowboy_websocket.ezdoc
+++ b/doc/src/manual/cowboy_websocket.ezdoc
@@ -2,8 +2,25 @@
 
 The `cowboy_websocket` module implements the Websocket protocol.
 
-The callbacks for websocket handlers are defined in the manual
-for the `cowboy_websocket_handler` behaviour.
+This module is a sub protocol that defines four callbacks to
+be implemented by handlers. The `init/2` and `terminate/3`
+callbacks are common to all handler types and are documented
+in the manual for the ^cowboy_handler module.
+
+The `websocket_handle/3` and `websocket_info/3` callbacks are
+specific to Websocket handlers and will be called as many times
+as necessary until the Websocket connection is closed.
+
+The `init/2` callback can be used to negotiate Websocket protocol
+extensions with the client. It is highly recommended to return a
+timeout value from this callback to ensure that the process is
+terminated when no data has been received during that timespan.
+The default timeout is `infinity`, which should only be used if
+you have alternate means of ending inactive connections.
+
+Cowboy will terminate the process right after closing the
+Websocket connection. This means that there is no real need to
+perform any cleanup in the optional `terminate/3` callback.
 
 :: Types
 
@@ -31,6 +48,118 @@ Type: 7 | 8 | 13
 
 The version of the Websocket protocol being used.
 
+:: Terminate reasons
+
+The following values may be received as the terminate reason
+in the optional `terminate/3` callback.
+
+: normal
+
+The connection was closed normally before establishing a Websocket
+connection. This typically happens if an `ok` tuple is returned
+from the `init/2` callback.
+
+: remote
+
+The remote endpoint closed the connection without giving any
+further details.
+
+: {remote, Code, Payload}
+
+The remote endpoint closed the connection with the given
+`Code` and `Payload` as the reason.
+
+: shutdown
+
+The handler requested to close the connection, either by returning
+a `shutdown` tuple or by sending a `close` frame.
+
+: timeout
+
+The connection has been closed due to inactivity. The timeout
+value can be configured from `init/2`.
+
+: {crash, Class, Reason}
+
+A crash occurred in the handler. `Class` and `Reason` can be
+used to obtain more information about the crash. The function
+`erlang:get_stacktrace/0` can also be called to obtain the
+stacktrace of the process when the crash occurred.
+
+: {error, badencoding}
+
+A text frame was sent by the client with invalid encoding. All
+text frames must be valid UTF-8.
+
+: {error, badframe}
+
+A protocol error has been detected.
+
+: {error, closed}
+
+The socket has been closed brutally without a close frame being
+received first.
+
+: {error, Reason}
+
+A socket error ocurred.
+
+:: Callbacks
+
+: websocket_handle(InFrame, Req, State)
+	-> {ok, Req, State}
+	| {ok, Req, State, hibernate}
+	| {reply, OutFrame | [OutFrame], Req, State}
+	| {reply, OutFrame | [OutFrame], Req, State, hibernate}
+	| {shutdown, Req, State}
+
+Types:
+
+* InFrame = {text | binary | ping | pong, binary()}
+* Req = cowboy_req:req()
+* State = any()
+* OutFrame = frame()
+
+Handle the data received from the Websocket connection.
+
+This function will be called every time data is received
+from the Websocket connection.
+
+The `shutdown` return value can be used to close the
+connection. A close reply will also result in the connection
+being closed.
+
+The `hibernate` option will hibernate the process until
+it receives new data from the Websocket connection or an
+Erlang message.
+
+: websocket_info(Info, Req, State)
+	-> {ok, Req, State}
+	| {ok, Req, State, hibernate}
+	| {reply, OutFrame | [OutFrame], Req, State}
+	| {reply, OutFrame | [OutFrame], Req, State, hibernate}
+	| {shutdown, Req, State}
+
+Types:
+
+* Info = any()
+* Req = cowboy_req:req()
+* State = any()
+* OutFrame = frame()
+
+Handle the Erlang message received.
+
+This function will be called every time an Erlang message
+has been received. The message can be any Erlang term.
+
+The `shutdown` return value can be used to close the
+connection. A close reply will also result in the connection
+being closed.
+
+The `hibernate` option will hibernate the process until
+it receives another message or new data from the Websocket
+connection.
+
 :: Exports
 
 None.