add extractors info to guide

CHANGES.md

@@ -4,6 +4,9 @@
 
 * Type-safe path/query parameter handling, using serde #70
 
+* HttpResponse builder's methods  `.body()`, `.finish()`, `.json()`
+  return `HttpResponse` instead of `Result`
+
 * Use more ergonomic `actix_web::Error` instead of `http::Error` for `HttpResponseBuilder::body()`
 
 * Use more ergonomic `actix_web::Error` instead of `http::Error` for `ClientRequestBuilder::body()`

guide/src/qs_5.md

@@ -329,9 +329,7 @@ It uses *serde* package as a deserialization library.
 has to implement *serde's *`Deserialize` trait.
 
 ```rust
-# extern crate bytes;
 # extern crate actix_web;
-# extern crate futures;
 #[macro_use] extern crate serde_derive;
 use actix_web::{App, Path, Result, http::Method};
 
@@ -352,6 +350,27 @@ fn main() {
 }
 ```
 
+It also possible to extract path information to a tuple, in this case you don't need
+to define extra type, just use tuple for as a `Path` generic type.
+
+Here is previous example re-written using tuple instead of specific type.
+
+```rust
+# extern crate actix_web;
+use actix_web::{App, Path, Result, http::Method};
+
+// extract path info using serde
+fn index(info: Path<(String, u32)>) -> Result<String> {
+    Ok(format!("Welcome {}! id: {}", info.0, info.1))
+}
+
+fn main() {
+    let app = App::new()
+        .resource("/{username}/{id}/index.html",    // <- define path parameters
+                  |r| r.method(Method::GET).with(index));
+}
+```
+
 [Query](../actix_web/struct.Query.html) provides similar functionality for
 request query parameters.
 

guide/src/qs_7.md

@@ -58,9 +58,36 @@ fn index(req: HttpRequest) -> HttpResponse {
 
 ## JSON Request
 
-There are two options for json body deserialization.
+There are several options for json body deserialization.
 
-The first option is to use *HttpResponse::json()*. This method returns a
+The first option is to use *Json* extractor. You define handler function
+that accepts `Json<T>` as a parameter and use `.with()` method for registering
+this handler. It is also possible to accept arbitrary valid json object by
+using `serde_json::Value` as a type `T`
+
+```rust
+# extern crate actix_web;
+#[macro_use] extern crate serde_derive;
+use actix_web::{App, Json, Result, http};
+
+#[derive(Deserialize)]
+struct Info {
+    username: String,
+}
+
+/// extract `Info` using serde
+fn index(info: Json<Info>) -> Result<String> {
+    Ok(format!("Welcome {}!", info.username))
+}
+
+fn main() {
+    let app = App::new().resource(
+       "/index.html",
+       |r| r.method(http::Method::POST).with(index));  // <- use `with` extractor
+}
+```
+
+The second option is to use *HttpResponse::json()*. This method returns a
 [*JsonBody*](../actix_web/dev/struct.JsonBody.html) object which resolves into
 the deserialized value.
 
@@ -128,7 +155,7 @@ A complete example for both options is available in
 
 ## JSON Response
 
-The `Json` type allows you to respond with well-formed JSON data: simply return a value of
+The `Json` type allows to respond with well-formed JSON data: simply return a value of
 type Json<T> where T is the type of a structure to serialize into *JSON*. The
 type `T` must implement the `Serialize` trait from *serde*.
 

src/json.rs

@@ -47,9 +47,7 @@ use httpresponse::HttpResponse;
 /// ## Example
 ///
 /// ```rust
-/// # extern crate bytes;
 /// # extern crate actix_web;
-/// # extern crate futures;
 /// #[macro_use] extern crate serde_derive;
 /// use actix_web::{App, Json, Result, http};
 ///

src/pred.rs

@@ -8,7 +8,8 @@ use httprequest::HttpRequest;
 
 /// Trait defines resource route predicate.
 /// Predicate can modify request object. It is also possible to
-/// to store extra attributes on request by using `.extensions()` method.
+/// to store extra attributes on request by using `Extensions` container,
+/// Extensions container available via `HttpRequest::extensions()` method.
 pub trait Predicate<S> {
 
     /// Check if request matches predicate

src/server/mod.rs

@@ -126,12 +126,16 @@ impl HttpHandler for Box<HttpHandler> {
     }
 }
 
+#[doc(hidden)]
 pub trait HttpHandlerTask {
 
+    /// Poll task, this method is used before or after *io* object is available
     fn poll(&mut self) -> Poll<(), Error>;
 
+    /// Poll task when *io* object is available
     fn poll_io(&mut self, io: &mut Writer) -> Poll<bool, Error>;
 
+    /// Connection is disconnected
     fn disconnected(&mut self);
 }
 
@@ -152,12 +156,14 @@ impl<T: HttpHandler> IntoHttpHandler for T {
     }
 }
 
+#[doc(hidden)]
 #[derive(Debug)]
 pub enum WriterState {
     Done,
     Pause,
 }
 
+#[doc(hidden)]
 /// Stream writer
 pub trait Writer {
     fn written(&self) -> u64;
@@ -172,6 +178,7 @@ pub trait Writer {
     fn poll_completed(&mut self, shutdown: bool) -> Poll<(), io::Error>;
 }
 
+#[doc(hidden)]
 /// Low-level io stream operations
 pub trait IoStream: AsyncRead + AsyncWrite + 'static {
     fn shutdown(&mut self, how: Shutdown) -> io::Result<()>;

src/ws/mod.rs

@@ -10,7 +10,7 @@
 //! # extern crate actix_web;
 //! # use actix::*;
 //! # use actix_web::*;
-//! use actix_web::ws;
+//! use actix_web::{ws, HttpRequest, HttpResponse};
 //!
 //! // do websocket handshake and start actor
 //! fn ws_index(req: HttpRequest) -> Result<HttpResponse> {