re-arrange exports, some doc string updates

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "actix-web"
-version = "0.4.11"
+version = "0.5.0-dev"
 authors = ["Nikolay Kim <fafhrd91@gmail.com>"]
 description = "Actix web is a simple, pragmatic, extremely fast, web framework for Rust."
 readme = "README.md"

src/fs.rs

@@ -433,7 +433,7 @@ impl<S: 'static> StaticFiles<S> {
         self
     }
 
-    /// Sets default resource which is used when no matched file could be found.
+    /// Sets default handler which is used when no matched file could be found.
     pub fn default_handler<H: Handler<S>>(mut self, handler: H) -> StaticFiles<S> {
         self.default = Box::new(WrapHandler::new(handler));
         self

src/httprequest.rs

@@ -20,7 +20,7 @@ use router::Router;
 use payload::Payload;
 use httpmessage::HttpMessage;
 use httpresponse::{HttpResponse, HttpResponseBuilder};
-use helpers::SharedHttpInnerMessage;
+use server::helpers::SharedHttpInnerMessage;
 use error::{UrlGenerationError, CookieParseError, PayloadError};
 
 

src/json.rs

@@ -1,4 +1,5 @@
 use std::fmt;
+use std::ops::{Deref, DerefMut};
 use bytes::{Bytes, BytesMut};
 use futures::{Poll, Future, Stream};
 use http::header::CONTENT_LENGTH;
@@ -15,11 +16,15 @@ use httprequest::HttpRequest;
 use httpresponse::HttpResponse;
 use extractor::HttpRequestExtractor;
 
-/// Json response helper
+/// Json helper
 ///
-/// The `Json` type allows you 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*.
+/// Json can be used for two different purpose. First is for json response generation
+/// and second is for extracting typed information from request's payload.
+///
+/// The `Json` type allows you 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*.
 ///
 /// ```rust
 /// # extern crate actix_web;
@@ -36,8 +41,52 @@ use extractor::HttpRequestExtractor;
 /// }
 /// # fn main() {}
 /// ```
+///
+/// To extract typed information from request's body, the type `T` must implement the
+/// `Deserialize` trait from *serde*.
+///
+/// ## Example
+///
+/// ```rust
+/// # extern crate bytes;
+/// # extern crate actix_web;
+/// # extern crate futures;
+/// #[macro_use] extern crate serde_derive;
+/// # use actix_web::*;
+/// use actix_web::Json;
+///
+/// #[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 = Application::new().resource(
+///        "/index.html",
+///        |r| r.method(Method::POST).with(index));  // <- use `with` extractor
+/// }
+/// ```
 pub struct Json<T>(pub T);
 
+impl<T> Deref for Json<T> {
+    type Target = T;
+
+    fn deref(&self) -> &T {
+        &self.0
+    }
+}
+
+impl<T> DerefMut for Json<T> {
+    fn deref_mut(&mut self) -> &mut T {
+        &mut self.0
+    }
+}
+
 impl<T> fmt::Debug for Json<T> where T: fmt::Debug {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(f, "Json: {:?}", self.0)

src/lib.rs

@@ -107,7 +107,6 @@ mod application;
 mod body;
 mod context;
 mod handler;
-mod helpers;
 mod httpmessage;
 mod httprequest;
 mod httpresponse;
@@ -141,8 +140,6 @@ pub use httpmessage::HttpMessage;
 pub use httprequest::HttpRequest;
 pub use httpresponse::HttpResponse;
 pub use handler::{Either, Responder, NormalizePath, AsyncResponder, FutureResponse};
-pub use route::Route;
-pub use resource::Resource;
 pub use context::HttpContext;
 pub use server::HttpServer;
 pub use extractor::{Path, Query};
@@ -163,14 +160,19 @@ pub(crate) const HAS_TLS: bool = false;
 #[doc(hidden)]
 #[deprecated(since="0.4.4", note="please use `actix::header` module")]
 pub mod headers {
-//! Headers implementation
-
+    //! Headers implementation
     pub use httpresponse::ConnectionType;
     pub use cookie::{Cookie, CookieBuilder};
     pub use http_range::HttpRange;
     pub use header::ContentEncoding;
 }
 
+pub mod helpers {
+    //! Various helpers
+
+    pub use handler::{NormalizePath};
+}
+
 pub mod dev {
 //! The `actix-web` prelude for library developers
 //!
@@ -186,6 +188,8 @@ pub mod dev {
     pub use context::Drain;
     pub use info::ConnectionInfo;
     pub use handler::{Handler, Reply};
+    pub use route::Route;
+    pub use resource::Resource;
     pub use with::WithHandler;
     pub use json::JsonBody;
     pub use router::{Router, Pattern};

src/server/h1writer.rs

@@ -8,11 +8,11 @@ use tokio_io::AsyncWrite;
 use http::{Method, Version};
 use http::header::{HeaderValue, CONNECTION, CONTENT_LENGTH, DATE};
 
-use helpers;
 use body::{Body, Binary};
 use headers::ContentEncoding;
 use httprequest::HttpInnerMessage;
 use httpresponse::HttpResponse;
+use super::helpers;
 use super::{Writer, WriterState, MAX_WRITE_BUFFER_SIZE};
 use super::shared::SharedBytes;
 use super::encoding::ContentEncoder;

src/server/h2writer.rs

@@ -9,11 +9,11 @@ use http2::server::SendResponse;
 use http::{Version, HttpTryFrom, Response};
 use http::header::{HeaderValue, CONNECTION, TRANSFER_ENCODING, DATE, CONTENT_LENGTH};
 
-use helpers;
 use body::{Body, Binary};
 use headers::ContentEncoding;
 use httprequest::HttpInnerMessage;
 use httpresponse::HttpResponse;
+use super::helpers;
 use super::encoding::ContentEncoder;
 use super::shared::SharedBytes;
 use super::settings::WorkerSettings;

src/server/mod.rs

@@ -16,6 +16,7 @@ mod h2;
 mod h1writer;
 mod h2writer;
 mod settings;
+pub(crate) mod helpers;
 pub(crate) mod shared;
 pub(crate) mod utils;
 

src/server/settings.rs

@@ -8,7 +8,7 @@ use bytes::BytesMut;
 use http::StatusCode;
 use futures_cpupool::{Builder, CpuPool};
 
-use helpers;
+use super::helpers;
 use super::KeepAlive;
 use super::channel::Node;
 use super::shared::{SharedBytes, SharedBytesPool};

src/ws/client.rs

@@ -268,6 +268,10 @@ struct Inner {
     closed: bool,
 }
 
+/// Future that implementes client websocket handshake process.
+///
+/// It resolves to a pair of `ClientReadr` and `ClientWriter` that
+/// can be used for reading and writing websocket frames.
 pub struct ClientHandshake {
     request: Option<SendRequest>,
     tx: Option<UnboundedSender<Bytes>>,

src/ws/mod.rs

@@ -82,7 +82,7 @@ pub type WsError = ProtocolError;
 #[deprecated(since="0.4.2", note="please use `ws::HandshakeError` instead")]
 pub type WsHandshakeError = HandshakeError;
 
-/// Websocket errors
+/// Websocket protocol errors
 #[derive(Fail, Debug)]
 pub enum ProtocolError {
     /// Received an unmasked frame from client