From acd89f61161820a0acde354e3cbd8da1600d0aa4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Fri, 18 Jan 2013 00:15:00 +0100
Subject: Explain how to write custom protocol upgrades in the guide

---
 guide/handlers.md | 22 +++++++++++++++++++---
 guide/toc.md      |  1 +
 2 files changed, 20 insertions(+), 3 deletions(-)

(limited to 'guide')

diff --git a/guide/handlers.md b/guide/handlers.md
index dac5460..e2c1264 100644
--- a/guide/handlers.md
+++ b/guide/handlers.md
@@ -33,7 +33,23 @@ init(_Any, _Req, _Opts) ->
     {upgrade, protocol, my_protocol}.
 ```
 
-The `my_protocol` module will be used for further processing of the
-request. It requires only one callback, `upgrade/4`.
+Cowboy comes with two protocol upgrades: `cowboy_rest` and
+`cowboy_websocket`. Use these values in place of `my_protocol`
+to use them.
 
-@todo Describe `upgrade/4` when the middleware code gets pushed.
+Custom protocol upgrades
+------------------------
+
+The `my_protocol` module above will be used for further processing
+of the request. It requires only one callback, `upgrade/4`.
+
+It receives the request object, the middleware environment, and
+the handler this request has been routed to along with its options.
+
+``` erlang
+upgrade(Req, Env, Handler, HandlerOpts) ->
+    %% ...
+```
+
+This callback is expected to behave like any middleware. Please
+see the corresponding chapter for more information.
diff --git a/guide/toc.md b/guide/toc.md
index c406629..fd711df 100644
--- a/guide/toc.md
+++ b/guide/toc.md
@@ -15,6 +15,7 @@ Cowboy User Guide
  *  [Handlers](handlers.md)
    *  Purpose
    *  Protocol upgrades
+   *  Custom protocol upgrades
  *  [HTTP handlers](http_handlers.md)
    *  Purpose
    *  Callbacks
-- 
cgit v1.2.3