signal: Add some examples to crate docs

Closes alexcrichton/tokio-signal#11

.travis.yml

@@ -11,6 +11,7 @@ script:
   - cargo build
   - cargo test
   - cargo doc --no-deps
+  - rustdoc --test README.md -L target/debug/deps
 after_success:
   - travis-cargo --only nightly doc-upload
 env:

README.md

@@ -15,10 +15,32 @@ First, add this to your `Cargo.toml`:
 tokio-signal = "0.1"
 ```
 
-Next, add this to your crate:
+Next you an use this in conjunction with the `tokio-core` and `futures` crates:
 
-```rust
+```rust,no_run
+extern crate futures;
+extern crate tokio_core;
 extern crate tokio_signal;
+
+use tokio_core::reactor::Core;
+use futures::{Future, Stream};
+
+fn main() {
+    let mut core = Core::new().unwrap();
+    let handle = core.handle();
+
+    // Create an infinite stream of "Ctrl+C" notifications. Each item received
+    // on this stream may represent multiple ctrl-c signals.
+    let ctrl_c = tokio_signal::ctrl_c(&handle).flatten_stream();
+
+    // Process each ctrl-c as it comes in
+    let prog = ctrl_c.for_each(|()| {
+        println!("ctrl-c received!");
+        Ok(())
+    });
+
+    core.run(prog).unwrap();
+}
 ```
 
 # License

src/lib.rs

@@ -13,11 +13,67 @@
 //! The are some fundamental limitations of this crate documented on the
 //! `Signal` structure as well.
 //!
-//! > **Note**: This crate compiles on Windows, but currently contains no
-//! >           bindings. Windows does not have signals like Unix does, but it
-//! >           does have a way to receive ctrl-c notifications at the console.
-//! >           It's planned that this will be bound and exported outside the
-//! >           `unix` module in the future!
+//! # Examples
+//!
+//! Print out all ctrl-C notifications received
+//!
+//! ```rust,no_run
+//! extern crate futures;
+//! extern crate tokio_core;
+//! extern crate tokio_signal;
+//!
+//! use tokio_core::reactor::Core;
+//! use futures::{Future, Stream};
+//!
+//! fn main() {
+//!     let mut core = Core::new().unwrap();
+//!     let handle = core.handle();
+//!
+//!     // Create an infinite stream of "Ctrl+C" notifications. Each item received
+//!     // on this stream may represent multiple ctrl-c signals.
+//!     let ctrl_c = tokio_signal::ctrl_c(&handle).flatten_stream();
+//!
+//!     // Process each ctrl-c as it comes in
+//!     let prog = ctrl_c.for_each(|()| {
+//!         println!("ctrl-c received!");
+//!         Ok(())
+//!     });
+//!
+//!     core.run(prog).unwrap();
+//! }
+//! ```
+//!
+//! Wait for SIGHUP on Unix
+//!
+//! ```rust,no_run
+//! # extern crate futures;
+//! # extern crate tokio_core;
+//! # extern crate tokio_signal;
+//! # #[cfg(unix)]
+//! # mod foo {
+//! #
+//! extern crate futures;
+//! extern crate tokio_core;
+//! extern crate tokio_signal;
+//!
+//! use tokio_core::reactor::Core;
+//! use futures::{Future, Stream};
+//! use tokio_signal::unix::{Signal, SIGHUP};
+//!
+//! fn main() {
+//!     let mut core = Core::new().unwrap();
+//!     let handle = core.handle();
+//!
+//!     // Like the previous example, this is an infinite stream of signals
+//!     // being received, and signals may be coalesced while pending.
+//!     let stream = Signal::new(SIGHUP, &handle).flatten_stream();
+//!
+//!     // Convert out stream into a future and block the program
+//!     core.run(stream.into_future()).ok().unwrap();
+//! }
+//! # }
+//! # fn main() {}
+//! ```
 
 #![doc(html_root_url = "https://docs.rs/tokio-signal/0.1")]
 #![deny(missing_docs)]