guide: add a testing section to the contributing guide (#598)

tokio-timer/src/timeout.rs

@@ -33,8 +33,10 @@ use std::time::{Instant, Duration};
 /// ```rust
 /// # extern crate futures;
 /// # extern crate tokio;
-/// use tokio::timer::Timeout;
-/// use futures::{Future, Stream};
+/// // import the `timeout` function, usually this is done
+/// // with `use tokio::prelude::*`
+/// use tokio::prelude::FutureExt;
+/// use futures::Stream;
 /// use futures::sync::mpsc;
 /// use std::time::Duration;
 ///
@@ -42,13 +44,17 @@ use std::time::{Instant, Duration};
 /// let (tx, rx) = mpsc::unbounded();
 /// # tx.unbounded_send(()).unwrap();
 /// # drop(tx);
+///
 /// let process = rx.for_each(|item| {
 ///     // do something with `item`
 /// # drop(item);
 /// # Ok(())
 /// });
 ///
-/// Timeout::new(process, Duration::from_secs(1));
+/// # tokio::runtime::current_thread::block_on_all(
+/// // Wrap the future with a `Timeout` set to expire in 10 milliseconds.
+/// process.timeout(Duration::from_millis(10))
+/// # ).unwrap();
 /// # }
 /// ```
 ///
@@ -94,6 +100,29 @@ impl<T> Timeout<T> {
     /// See [type] level documentation for more details.
     ///
     /// [type]: #
+    ///
+    /// # Examples
+    ///
+    /// Create a new `Timeout` set to expire in 10 milliseconds.
+    ///
+    /// ```rust
+    /// # extern crate futures;
+    /// # extern crate tokio;
+    /// use tokio::timer::Timeout;
+    /// use futures::Future;
+    /// use futures::sync::oneshot;
+    /// use std::time::Duration;
+    ///
+    /// # fn main() {
+    /// let (tx, rx) = oneshot::channel();
+    /// # tx.send(()).unwrap();
+    ///
+    /// # tokio::runtime::current_thread::block_on_all(
+    /// // Wrap the future with a `Timeout` set to expire in 10 milliseconds.
+    /// Timeout::new(rx, Duration::from_millis(10))
+    /// # ).unwrap();
+    /// # }
+    /// ```
     pub fn new(value: T, timeout: Duration) -> Timeout<T> {
         let delay = Delay::new_timeout(now() + timeout, timeout);