Describe arguments of the HTTP handler callbacks

2 files changed, 20 insertions, 9 deletions

diff --git a/guide/http_handlers.md b/guide/http_handlers.md
index aba0e06..f3ac185 100644
--- a/guide/http_handlers.md
+++ b/guide/http_handlers.md
@@ -10,17 +10,26 @@ Usage
 -----
 
 You need to implement three callbacks for HTTP handlers. The first,
-`init/3`, is common to all handlers. In the context of HTTP handlers
-this should be used for any initialization needs.
+`init/3`, is common to all handlers. It receives three arguments:
+a tuple containing the transport and protocol in use, the `Req` object
+and the handler options you defined in the routes. In the context of
+HTTP handlers this should be used for any initialization needs. For
+example you can initialize here the `State` variable that will be
+passed to the following functions.
 
 The second callback, `handle/2`, is where most of your code should
-be. As the name explains, this is where you handle the request.
+be. It receives two arguments: the `Req` object and the `State`
+previously defined. As the name explains, this is where you handle
+the request.
 
 The last callback, `terminate/3`, will be empty most of the time.
-It's used for any needed cleanup. If you used the process dictionary,
-timers, monitors then you most likely want to stop them in this
-callback, as Cowboy might end up reusing this process for subsequent
-requests. Please see the Internals chapter for more information.
+It receives three arguments: the `Reason` for termination, the `Req`
+object and the `State` previously defined. This callback should be
+used strictly for cleaning up. Replying using the `Req` is disallowed.
+If you used the process dictionary, timers, monitors then you most
+likely want to stop them in this callback, as Cowboy might end up
+reusing this process for subsequent requests. Please see the
+Internals chapter for more information.
 
 Of course the general advice is to not use the process dictionary,
 and that any operation requiring reception of messages should be
diff --git a/guide/introduction.md b/guide/introduction.md
index e5616b0..a7f35a2 100644
--- a/guide/introduction.md
+++ b/guide/introduction.md
@@ -108,8 +108,10 @@ handlers, Websocket handlers, REST handlers and static handlers. Their
 usage is documented in the respective sections of the guide.
 
 Most applications use the plain HTTP handler, which has three callback
-functions: init/3, handle/2 and terminate/3. Following is an example of
-a simple handler module.
+functions: init/3, handle/2 and terminate/3. You can find more information
+about the arguments and possible return values of these callbacks in the
+HTTP handlers section of this guide. Following is an example of a simple
+HTTP handler module.
 
 ``` erlang
 -module(my_handler).