std::io: expand the oneshot/periodic docs.

Examples!

Fixes #14714.

src/libstd/io/timer.rs

@@ -96,27 +96,87 @@ impl Timer {
     }
 
     /// Creates a oneshot receiver which will have a notification sent when
-    /// `msecs` milliseconds has elapsed. This does *not* block the current
-    /// task, but instead returns immediately.
+    /// `msecs` milliseconds has elapsed.
+    ///
+    /// This does *not* block the current task, but instead returns immediately.
     ///
     /// Note that this invalidates any previous receiver which has been created
     /// by this timer, and that the returned receiver will be invalidated once
-    /// the timer is destroyed (when it falls out of scope).
+    /// the timer is destroyed (when it falls out of scope). In particular, if
+    /// this is called in method-chaining style, the receiver will be
+    /// invalidated at the end of that statement, and all `recv` calls will
+    /// fail.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use std::io::timer::Timer;
+    ///
+    /// let mut timer = Timer::new().unwrap();
+    /// let ten_milliseconds = timer.oneshot(10);
+    ///
+    /// for _ in range(0, 100) { /* do work */ }
+    ///
+    /// // blocks until 10 ms after the `oneshot` call
+    /// ten_milliseconds.recv();
+    /// ```
+    ///
+    /// ```rust
+    /// use std::io::timer::Timer;
+    ///
+    /// // Incorrect, method chaining-style:
+    /// let mut five_ms = Timer::new().unwrap().oneshot(5);
+    /// // The timer object was destroyed, so this will always fail:
+    /// // five_ms.recv()
+    /// ```
     pub fn oneshot(&mut self, msecs: u64) -> Receiver<()> {
         let (tx, rx) = channel();
         self.obj.oneshot(msecs, box TimerCallback { tx: tx });
         return rx
     }
 
     /// Creates a receiver which will have a continuous stream of notifications
-    /// being sent every `msecs` milliseconds. This does *not* block the
-    /// current task, but instead returns immediately. The first notification
-    /// will not be received immediately, but rather after `msec` milliseconds
-    /// have passed.
+    /// being sent every `msecs` milliseconds.
+    ///
+    /// This does *not* block the current task, but instead returns
+    /// immediately. The first notification will not be received immediately,
+    /// but rather after `msec` milliseconds have passed.
     ///
     /// Note that this invalidates any previous receiver which has been created
     /// by this timer, and that the returned receiver will be invalidated once
-    /// the timer is destroyed (when it falls out of scope).
+    /// the timer is destroyed (when it falls out of scope). In particular, if
+    /// this is called in method-chaining style, the receiver will be
+    /// invalidated at the end of that statement, and all `recv` calls will
+    /// fail.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use std::io::timer::Timer;
+    ///
+    /// let mut timer = Timer::new().unwrap();
+    /// let ten_milliseconds = timer.periodic(10);
+    ///
+    /// for _ in range(0, 100) { /* do work */ }
+    ///
+    /// // blocks until 10 ms after the `periodic` call
+    /// ten_milliseconds.recv();
+    ///
+    /// for _ in range(0, 100) { /* do work */ }
+    ///
+    /// // blocks until 20 ms after the `periodic` call (*not* 10ms after the
+    /// // previous `recv`)
+    /// ten_milliseconds.recv();
+    /// ```
+    ///
+    /// ```rust
+    /// use std::io::timer::Timer;
+    ///
+    /// // Incorrect, method chaining-style.
+    /// let mut five_ms = Timer::new().unwrap().periodic(5);
+    /// // The timer object was destroyed, so this will always fail:
+    /// // five_ms.recv()
+    /// ```
     pub fn periodic(&mut self, msecs: u64) -> Receiver<()> {
         let (tx, rx) = channel();
         self.obj.period(msecs, box TimerCallback { tx: tx });