---

yaml
---
r: 127738
b: refs/heads/snap-stage3
c: 734834c
h: refs/heads/master
v: v3

Author: brson

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 49a970f2449a78f28b6c301e542d38593094ca77
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 8a5fe8655af5b8927cb6868d715c5bd9fa30c3b3
+refs/heads/snap-stage3: 734834c7d6e4862c8348a8c9660bb338773047ca
 refs/heads/try: d9c23fcbaea89871667272a67ecb8d3a512162f3
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/src/libstd/io/timer.rs

@@ -114,6 +114,29 @@ impl Timer {
     /// 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;
+    ///
+    /// let mut timer = Timer::new().unwrap();
+    /// let ten_milliseconds = timer.oneshot(10);
+    ///
+    /// for _ in range(0u, 100) { /* do work */ }
+    ///
+    /// // blocks until 10 ms after the `oneshot` call
+    /// ten_milliseconds.recv();
+    /// ```
+    ///
+    /// ```rust
+    /// use std::io::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, duration: Duration) -> Receiver<()> {
         let (tx, rx) = channel();
         self.obj.oneshot(in_ms(duration), box TimerCallback { tx: tx });
@@ -133,6 +156,35 @@ impl Timer {
     /// 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;
+    ///
+    /// let mut timer = Timer::new().unwrap();
+    /// let ten_milliseconds = timer.periodic(10);
+    ///
+    /// for _ in range(0u, 100) { /* do work */ }
+    ///
+    /// // blocks until 10 ms after the `periodic` call
+    /// ten_milliseconds.recv();
+    ///
+    /// for _ in range(0u, 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;
+    ///
+    /// // 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, duration: Duration) -> Receiver<()> {
         let (tx, rx) = channel();
         self.obj.period(in_ms(duration), box TimerCallback { tx: tx });