More request object documentation in the guide

guide/req.md

@@ -15,14 +15,59 @@ while others will not. For example, obtaining request headers
 can be repeated safely. Obtaining the request body can only
 be done once, as it is read directly from the socket.
 
-All calls to the `cowboy_req` module will return an updated
+With few exceptions, all calls to the `cowboy_req` module
-request object. You MUST use the new request object instead
+will return an updated request object. You MUST use the new
-of the old one for all subsequent operations.
+request object instead of the old one for all subsequent
+operations.
 
 Request
 -------
 
-@todo Describe.
+Cowboy allows you to retrieve a lot of information about
+the request. All these calls return a `{Value, Req}` tuple,
+with `Value` the requested value and `Req` the updated
+request object.
+
+The following access functions are defined in `cowboy_req`:
+
+ *  `method/1`: the request method (`<<"GET">>`, `<<"POST">>`...)
+ *  `version/1`: the HTTP version (`{1,0}` or `{1,1}`)
+ *  `peer/1`: the peer address and port number
+ *  `peer_addr/1`: the peer address guessed using the request headers
+ *  `host/1`: the hostname requested
+ *  `host_info/1`: the result of the `[...]` match on the host
+ *  `port/1`: the port number used for the connection
+ *  `path/1`: the path requested
+ *  `path_info/1`: the result of the `[...]` match on the path
+ *  `qs/1`: the entire query string unmodified
+ *  `qs_val/{2,3}`: the value for the requested query string key
+ *  `qs_vals/1`: all key/values found in the query string
+ *  `fragment/1`: the fragment part of the URL (e.g. `#nav-links`)
+ *  `host_url/1`: the requested URL without the path, qs and fragment
+ *  `url/1`: the requested URL
+ *  `binding/{2,3}`: the value for the requested binding found during routing
+ *  `bindings/1`: all key/values found during routing
+ *  `header/{2,3}`: the value for the requested header name
+ *  `headers/1`: all headers name/value
+ *  `cookie/{2,3}`: the value for the requested cookie name
+ *  `cookies/1`: all cookies name/value
+ *  `meta/{2,3}`: the meta information for the requested key
+
+All the functions above that can take two or three arguments
+take an optional third argument for the default value if
+none is found. Otherwise it will return `undefined`.
+
+In addition, Cowboy allows you to parse headers using the
+`parse_header/{2,3}` function, which takes a header name
+as lowercase binary, the request object, and an optional
+default value. It returns `{ok, ParsedValue, Req}` if it
+could be parsed, `{undefined, RawValue, Req}` if Cowboy
+doesn't know this header, and `{error, badarg}` if Cowboy
+encountered an error while trying to parse it.
+
+Finally, Cowboy allows you to set request meta information
+using the `set_meta/3` function, which takes a name, a value
+and the request object and returns the latter modified.
 
 Request body
 ------------