Add some examples of reading the content of a Response, and a paragraph about Read

src/lib.rs

@@ -22,14 +22,22 @@
 //!
 //! ## Making a GET request
 //!
-//! For a single request, you can use the `get` shortcut method.
-//!
+//! For a single request, you can use the [`get`][get] shortcut method.
 //!
 //! ```no_run
-//! let resp = reqwest::get("https://www.rust-lang.org").unwrap();
+//! use std::io::Read;
+//! let mut resp = reqwest::get("https://www.rust-lang.org").unwrap();
 //! assert!(resp.status().is_success());
+//!
+//! let mut content = String::new();
+//! resp.read_to_string(&mut content);
 //! ```
 //!
+//! As you can see, reqwest's [`Response`][response] struct implements Rust's
+//! `Read` trait, so many useful standard library and third party crates will
+//! have convenience methods that take a `Response` anywhere `T: Read` is
+//! acceptable.
+//!
 //! If you plan to perform multiple requests, it is best to create a [`Client`][client]
 //! and reuse it, taking advantage of keep-alive connection pooling.
 //!
@@ -86,6 +94,8 @@
 //!
 //! [hyper]: http://hyper.rs
 //! [client]: ./struct.Client.html
+//! [response]: ./struct.Response.html
+//! [get]: ./fn.get.html
 //! [builder]: ./client/struct.RequestBuilder.html
 //! [serde]: http://serde.rs
 extern crate hyper;
@@ -118,6 +128,19 @@ mod redirect;
 
 
 /// Shortcut method to quickly make a `GET` request.
+///
+/// See also the methods on the [`reqwest::Response`](./struct.Response.html)
+/// type.
+///
+/// # Examples
+///
+/// ```no_run
+/// use std::io::Read;
+///
+/// let mut result = String::new();
+/// reqwest::get("https://www.rust-lang.org").unwrap()
+///     .read_to_string(&mut result);
+/// ```
 pub fn get<T: IntoUrl>(url: T) -> ::Result<Response> {
     let client = try!(Client::new());
     client.get(url).send()