wip

src/async_impl/client.rs

@@ -23,6 +23,33 @@ static DEFAULT_USER_AGENT: &'static str =
     concat!(env!("CARGO_PKG_NAME"), "/", env!("CARGO_PKG_VERSION"));
 
 /// An asynchornous `Client` to make Requests with.
+///
+/// The Client has various configuration values to tweak, but the defaults
+/// are set to what is usually the most commonly desired value.
+///
+/// The `Client` holds a connection pool internally, so it is advised that
+/// you create one and **reuse** it.
+///
+/// # Examples
+///
+/// ```rust
+/// # #[cfg(features = "unstable")]
+/// # fn run() -> Result<(), Box<::std::error::Error>> {
+/// # extern crate tokio_core;
+/// # extern crate futures;
+/// use futures::Future;
+/// use tokio_core::reactor::Core;
+/// use reqwest::unstable::async::Client;
+///
+/// let mut core = Core::new()?;
+/// let client = Client::new(&core.handle());
+/// let fut = client.get("http://httpbin.org/").send();
+/// core.run(fut)?;
+/// #   Ok(())
+/// # }
+/// # fn main() {}
+/// ```
+
 #[derive(Clone)]
 pub struct Client {
     inner: Arc<ClientRef>,

src/async_impl/response.rs

@@ -51,27 +51,27 @@ impl Response {
         &mut self.headers
     }
 
-    /// Get a readable response body.
-    /// 
-    /// The response will be decoded.
-    #[inline]
-    pub fn body_mut(&mut self) -> &mut Decoder {
-        &mut self.body
-    }
-
-    /// Get a readable response body.
-    /// 
-    /// This function will replace the body on the response with an empty one.
+    /// Get a reference to the response body.
     #[inline]
     pub fn body(&self) -> &Decoder {
         &self.body
     }
 
+    /// Get a mutable reference to the response body.
+    ///
+    /// The chunks from the body may be decoded, depending on the `gzip`
+    /// option on the `ClientBuilder`.
+    #[inline]
+    pub fn body_mut(&mut self) -> &mut Decoder {
+        &mut self.body
+    }
+
+
     /// Try to deserialize the response body as JSON using `serde`.
     #[inline]
     pub fn json<T: DeserializeOwned>(&mut self) -> Json<T> {
         let body = mem::replace(&mut self.body, Decoder::empty());
-        
+
         Json {
             concat: body.concat2(),
             _marker: PhantomData,
@@ -79,28 +79,28 @@ impl Response {
     }
 
     /// Turn a response into an error if the server returned an error.
-    // XXX: example disabled since rustdoc still tries to run it
-    // when the 'unstable' feature isn't active, making the import
-    // fail.
-    //
-    // # Example
-    //
-    // ```
-    // # use reqwest::unstable::async::Response;
-    // fn on_response(res: Response) {
-    //     match res.error_for_status() {
-    //         Ok(_res) => (),
-    //         Err(err) => {
-    //             // asserting a 400 as an example
-    //             // it could be any status between 400...599
-    //             assert_eq!(
-    //                 err.status(),
-    //                 Some(reqwest::StatusCode::BadRequest)
-    //             );
-    //         }
-    //     }
-    // }
-    // ```
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # #[cfg(feature="unstable")]
+    /// # use reqwest::unstable::async::Response;
+    /// # #[cfg(feature="unstable")]
+    /// fn on_response(res: Response) {
+    ///     match res.error_for_status() {
+    ///         Ok(_res) => (),
+    ///         Err(err) => {
+    ///             // asserting a 400 as an example
+    ///             // it could be any status between 400...599
+    ///             assert_eq!(
+    ///                 err.status(),
+    ///                 Some(reqwest::StatusCode::BadRequest)
+    ///             );
+    ///         }
+    ///     }
+    /// }
+    /// # fn main() {}
+    /// ```
     #[inline]
     pub fn error_for_status(self) -> ::Result<Self> {
         if self.status.is_client_error() {

src/lib.rs

@@ -177,14 +177,16 @@ pub mod multipart;
 
 /// A set of unstable functionality.
 ///
-/// This module is only available when the `unstable` feature is enabled.
+/// This module is only available when the `unstable` [feature][] is enabled.
 /// There is no backwards compatibility guarantee for any of the types within.
+///
+/// [feature]: http://doc.crates.io/specifying-dependencies.html#choosing-features
 #[cfg(feature = "unstable")]
 pub mod unstable {
     /// An 'async' implementation of the reqwest `Client`.
     ///
     /// Relies on the `futures` crate, which is unstable, hence this module
-    /// is unstable.
+    /// is **unstable**.
     pub mod async {
         pub use ::async_impl::{
             Body,