update docs around ::get() and Response::text()

Closes #227

src/lib.rs

@@ -33,13 +33,15 @@
 //! use std::io::Read;
 //! # use reqwest::{Error, Response};
 //!
-//! # fn run() -> Result<Response, Error> {
+//! # fn run() -> Result<(), Error> {
 //! let mut resp = reqwest::get("https://www.rust-lang.org")?;
+//!
 //! assert!(resp.status().is_success());
 //!
-//! let mut content = String::new();
+//! let body = resp.text()?;
-//! resp.read_to_string(&mut content);
+//!
-//! # Ok(resp)
+//! println!("body = {:?}", body);
+//! # Ok(())
 //! # }
 //! ```
 //!
@@ -48,8 +50,9 @@
 //! 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]
+//! **NOTE**: If you plan to perform multiple requests, it is best to create a
-//! and reuse it, taking advantage of keep-alive connection pooling.
+//! [`Client`][client] and reuse it, taking advantage of keep-alive connection
+//! pooling.
 //!
 //! ## Making POST requests (or setting request bodies)
 //!
@@ -212,15 +215,16 @@ pub mod unstable {
 /// See also the methods on the [`reqwest::Response`](./struct.Response.html)
 /// type.
 ///
+/// **NOTE**: This function creates a new internal `Client` on each call,
+/// and so should not be used if making many requests. Create a
+/// [`Client`](./struct.Client.html) instead.
+///
 /// # Examples
 ///
 /// ```rust
-/// use std::io::Read;
+/// # fn run() -> Result<(), reqwest::Error> {
-///
+/// let body = reqwest::get("https://www.rust-lang.org")?
-/// # fn run() -> Result<(), Box<::std::error::Error>> {
+///     .text()?;
-/// let mut result = String::new();
-/// reqwest::get("https://www.rust-lang.org")?
-///     .read_to_string(&mut result)?;
 /// # Ok(())
 /// # }
 /// # fn main() { }