add multipart guide section

examples/multipart/src/main.rs

@@ -15,15 +15,15 @@ fn index(mut req: HttpRequest) -> Box<Future<Item=HttpResponse, Error=Error>>
 
     // get multipart stream and iterate over multipart items
     Box::new(
-        req.multipart()
+        req.multipart() // <- get multipart stream for current request
             .map_err(Error::from)
-            .and_then(|item| {
+            .and_then(|item| {  // <- iterate over multipart items
-                // Multipart stream is a stream of Fields and nested Multiparts
                 match item {
+                    // Handle multipart Field
                     multipart::MultipartItem::Field(field) => {
                         println!("==== FIELD ==== {:?}", field);
 
-                        // Read field's stream
+                        // Field in turn is stream of *Bytes* object
                         Either::A(
                             field.map_err(Error::from)
                                 .map(|chunk| {
@@ -32,12 +32,12 @@ fn index(mut req: HttpRequest) -> Box<Future<Item=HttpResponse, Error=Error>>
                                 .fold((), |_, _| result::<_, Error>(Ok(()))))
                     },
                     multipart::MultipartItem::Nested(mp) => {
-                        // Do nothing for nested multipart stream
+                        // Or item could be nested Multipart stream
                         Either::B(result(Ok(())))
                     }
                 }
             })
-            // wait until stream finish
+            // wait until stream finishes
             .fold((), |_, _| result::<_, Error>(Ok(())))
             .map(|_| httpcodes::HTTPOk.response())
     )

guide/src/qs_14.md

@@ -121,7 +121,7 @@ fn index(req: HttpRequest<State>) -> Box<Future<Item=HttpResponse, Error=Error>>
 ```
 
 Full example is available in 
-[examples repository](https://github.com/actix/actix-web/tree/master/examples/diesel/).
+[examples directory](https://github.com/actix/actix-web/tree/master/examples/diesel/).
 
 More information on sync actors could be found in 
 [actix documentation](https://docs.rs/actix/0.3.3/actix/sync/index.html).

guide/src/qs_7.md

@@ -114,9 +114,44 @@ fn index(req: HttpRequest) -> HttpResponse {
 
 ## Multipart body
 
+Actix provides multipart stream support. 
+[*Multipart*](../actix_web/multipart/struct.Multipart.html) is implemented as 
+a stream of multipart items, each item could be
+[*Field*](../actix_web/multipart/struct.Field.html) or nested *Multipart* stream.
+`HttpResponse::multipart()` method returns *Multipart* stream for current request.
 
+In simple form multipart stream handling could be implemented similar to this example
 
-[WIP]
+```rust,ignore
+# extern crate actix_web;
+use actix_web::*;
+
+fn index(req: HttpRequest) -> Box<Future<...>> {
+    req.multipart()        // <- get multipart stream for current request
+       .and_then(|item| {  // <- iterate over multipart items
+           match item {
+                           // Handle multipart Field
+              multipart::MultipartItem::Field(field) => {
+                 println!("==== FIELD ==== {:?} {:?}", field.heders(), field.content_type());
+                 
+                 Either::A(
+                           // Field in turn is a stream of *Bytes* objects
+                   field.map(|chunk| {
+                        println!("-- CHUNK: \n{}",
+                                 std::str::from_utf8(&chunk).unwrap());})
+                      .fold((), |_, _| result(Ok(()))))
+                },
+              multipart::MultipartItem::Nested(mp) => {
+                         // Or item could be nested Multipart stream 
+                 Either::B(result(Ok(())))
+              }
+         }
+   })
+}
+```
+
+Full example is available in 
+[examples directory](https://github.com/actix/actix-web/tree/master/examples/multipart/).
 
 ## Urlencoded body