Add documentation for the public interface.

This is probably not perfect yet but it should be better than
nothing. We'll improve things with feedback received from the
many users.

1 files changed, 26 insertions, 0 deletions

diff --git a/src/cowboy_http_websocket_handler.erl b/src/cowboy_http_websocket_handler.erl
index 30cb2e1..b02c28d 100644
--- a/src/cowboy_http_websocket_handler.erl
+++ b/src/cowboy_http_websocket_handler.erl
@@ -12,9 +12,35 @@
 %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
+%% @doc Handler for HTTP WebSocket requests.
+%%
+%% WebSocket handlers must implement three callbacks: <em>websocket_init/3</em>,
+%% <em>websocket_handle/3</em> and <em>websocket_terminate/3</em>. These
+%% callbacks will only be called if the connection is upgraded to WebSocket
+%% in the HTTP handler's <em>init/3</em> callback. They are then called in that
+%% order, although <em>websocket_handle/3</em> will be called multiple time,
+%% one time for each message or packet received.
+%%
+%% <em>websocket_init/3</em> is meant for initialization. It receives
+%% information about the transport and protocol used, along with the handler
+%% options from the dispatch list. You can define a request-wide state here.
+%% If you are going to want to compact the request, you should probably do it
+%% here.
+%%
+%% <em>websocket_handle/3</em> receives messages sent to the process and
+%% also the data sent to the socket. In the later case the information is
+%% given as a tuple <em>{websocket, Data}</em>. It can reply something, do
+%% nothing or close the connection. You can choose to hibernate the process
+%% by returning <em>hibernate</em> to save memory and CPU.
+%%
+%% <em>websocket_terminate/3</em> is meant for cleaning up. It also receives
+%% the request and the state previously defined, along with a reason for
+%% termination.
 -module(cowboy_http_websocket_handler).
+
 -export([behaviour_info/1]).
 
+%% @private
 -spec behaviour_info(_) -> undefined | [{websocket_handle, 3}
 	| {websocket_init, 3} | {websocket_terminate, 3}, ...].
 behaviour_info(callbacks) ->