doc(client): show spawning a client future, clarify lazy in client example

examples/client.rs

@@ -28,7 +28,14 @@ fn main() {
         return;
     }
 
-    rt::run(rt::lazy(move || {
+    // Run the runtime with the future trying to fetch and print this URL.
+    //
+    // Note that in more complicated use cases, the runtime should probably
+    // run on its own, and futures should just be spawned into it.
+    rt::run(fetch_url(url));
+}
+
+fn fetch_url(url: hyper::Uri) -> impl Future<Item=(), Error=()> {
     let client = Client::new();
 
     client
@@ -55,5 +62,4 @@ fn main() {
         .map_err(|err| {
             eprintln!("Error {}", err);
         })
-    }));
 }

src/client/mod.rs

@@ -23,20 +23,22 @@
 //!
 //! ## Example
 //!
-//! ```no_run
+//! For a small example program simply fetching a URL, take a look at the
+//! [full client example](https://github.com/hyperium/hyper/blob/master/examples/client.rs).
+//!
+//! ```
 //! extern crate hyper;
 //!
 //! use hyper::Client;
 //! # #[cfg(feature = "runtime")]
-//! use hyper::rt::{self, lazy, Future, Stream};
+//! use hyper::rt::{self, Future, Stream};
 //!
 //! # #[cfg(feature = "runtime")]
-//! fn main() {
-//!     // A runtime is needed to execute our asynchronous code.
-//!     rt::run(lazy(|| {
+//! # fn fetch_httpbin() {
 //! let client = Client::new();
 //!
-//!         client
+//! let fut = client
+//!
 //!     // Make a GET /ip to 'http://httpbin.org'
 //!     .get("http://httpbin.org/ip".parse().unwrap())
 //!
@@ -65,10 +67,13 @@
 //!     // Map any errors that might have happened...
 //!     .map_err(|err| {
 //!         println!("error: {}", err);
-//!             })
-//!     }));
-//! }
-//! # #[cfg(not(feature = "runtime"))]
+//!     });
+//!
+//! // A runtime is needed to execute our asynchronous code. In order to
+//! // spawn the future into the runtime, it should already have been
+//! // started and running before calling this this code.
+//! rt::spawn(fut);
+//! # }
 //! # fn main () {}
 //! ```