std: Fix all code examples

23 files changed, 147 insertions, 90 deletions

diff --git a/src/libstd/c_str.rs b/src/libstd/c_str.rs
index 38deaf2dbcb..a7e502be32e 100644
--- a/src/libstd/c_str.rs
+++ b/src/libstd/c_str.rs
@@ -51,13 +51,13 @@ let my_string = "Hello, world!";
 let my_c_string = my_string.to_c_str();
 my_c_string.with_ref(|c_buffer| {
     unsafe { puts(c_buffer); }
-})
+});
 
 // Don't save off the allocation of the C string, the `c_buffer` will be
 // deallocated when this block returns!
 my_string.with_c_str(|c_buffer| {
     unsafe { puts(c_buffer); }
-})
+});
  ```
 
 */
@@ -216,7 +216,11 @@ pub trait ToCStr {
     /// # Example
     ///
     /// ```rust
-    /// let s = "PATH".with_c_str(|path| libc::getenv(path))
+    /// use std::libc;
+    ///
+    /// let s = "PATH".with_c_str(|path| unsafe {
+    ///     libc::getenv(path)
+    /// });
     /// ```
     ///
     /// # Failure
diff --git a/src/libstd/cast.rs b/src/libstd/cast.rs
index c2dc7506105..05aab2f9570 100644
--- a/src/libstd/cast.rs
+++ b/src/libstd/cast.rs
@@ -49,7 +49,9 @@ pub unsafe fn bump_box_refcount<T>(t: @T) { forget(t); }
  * # Example
  *
  * ```rust
- * let v: &[u8] = transmute("L");
+ * use std::cast;
+ *
+ * let v: &[u8] = unsafe { cast::transmute("L") };
  * assert!(v == [76u8]);
  * ```
  */
diff --git a/src/libstd/comm/mod.rs b/src/libstd/comm/mod.rs
index 30324d9bc60..33d5d48ebdc 100644
--- a/src/libstd/comm/mod.rs
+++ b/src/libstd/comm/mod.rs
@@ -57,7 +57,7 @@
 //!
 //! # Example
 //!
-//! ```rust
+//! ```rust,should_fail
 //! // Create a simple streaming channel
 //! let (port, chan) = Chan::new();
 //! do spawn {
@@ -81,7 +81,7 @@
 //!
 //! // The call to recv() will fail!() because the channel has already hung
 //! // up (or been deallocated)
-//! let (port, chan) = Chan::new();
+//! let (port, chan) = Chan::<int>::new();
 //! drop(chan);
 //! port.recv();
 //! ```
diff --git a/src/libstd/comm/select.rs b/src/libstd/comm/select.rs
index 4d6b540f2a5..9c59a936085 100644
--- a/src/libstd/comm/select.rs
+++ b/src/libstd/comm/select.rs
@@ -25,7 +25,7 @@
 //!
 //! # Example
 //!
-//! ```rust
+//! ```rust,notest
 //! let (mut p1, c1) = Chan::new();
 //! let (mut p2, c2) = Chan::new();
 //!
@@ -40,6 +40,7 @@
 //!         assert_eq!(val, 2);
 //!     }
 //! )
+//! ```
 
 #[allow(dead_code)];
 
diff --git a/src/libstd/condition.rs b/src/libstd/condition.rs
index 1a4e9226ee8..2ecae8e85d0 100644
--- a/src/libstd/condition.rs
+++ b/src/libstd/condition.rs
@@ -23,13 +23,17 @@ A condition is declared through the `condition!` macro provided by the compiler:
 condition! {
     pub my_error: int -> ~str;
 }
- ```
+# fn main() {}
+```
 
 This macro declares an inner module called `my_error` with one static variable,
 `cond` that is a static `Condition` instance. To help understand what the other
 parameters are used for, an example usage of this condition would be:
 
 ```rust
+# condition! { pub my_error: int -> ~str; }
+# fn main() {
+
 my_error::cond.trap(|raised_int| {
 
     // the condition `my_error` was raised on, and the value it raised is stored
@@ -51,6 +55,8 @@ my_error::cond.trap(|raised_int| {
     println(my_error::cond.raise(4)); // prints "oh well"
 
 })
+
+# }
  ```
 
 Condition handling is useful in cases where propagating errors is either to
@@ -99,10 +105,12 @@ impl<T, U> Condition<T, U> {
     /// ```rust
     /// condition! { my_error: int -> int; }
     ///
+    /// # fn main() {
     /// let trap = my_error::cond.trap(|error| error + 3);
     ///
     /// // use `trap`'s inside method to register the handler and then run a
     /// // block of code with the handler registered
+    /// # }
     /// ```
     pub fn trap<'a>(&'a self, h: 'a |T| -> U) -> Trap<'a, T, U> {
         let h: Closure = unsafe { ::cast::transmute(h) };
@@ -176,10 +184,12 @@ impl<'a, T, U> Trap<'a, T, U> {
     /// ```rust
     /// condition! { my_error: int -> int; }
     ///
+    /// # fn main() {
     /// let result = my_error::cond.trap(|error| error + 3).inside(|| {
     ///     my_error::cond.raise(4)
     /// });
     /// assert_eq!(result, 7);
+    /// # }
     /// ```
     pub fn inside<V>(&self, inner: 'a || -> V) -> V {
         let _g = Guard { cond: self.cond };
diff --git a/src/libstd/fmt/mod.rs b/src/libstd/fmt/mod.rs
index b4f30311753..e4d45fddacb 100644
--- a/src/libstd/fmt/mod.rs
+++ b/src/libstd/fmt/mod.rs
@@ -34,12 +34,12 @@ arguments directly while performing minimal allocations.
 Some examples of the `format!` extension are:
 
 ```rust
-format!("Hello")                  // => ~"Hello"
-format!("Hello, {:s}!", "world")  // => ~"Hello, world!"
-format!("The number is {:d}", 1)  // => ~"The number is 1"
-format!("{:?}", ~[3, 4])          // => ~"~[3, 4]"
-format!("{value}", value=4)       // => ~"4"
-format!("{} {}", 1, 2)            // => ~"1 2"
+format!("Hello");                 // => ~"Hello"
+format!("Hello, {:s}!", "world"); // => ~"Hello, world!"
+format!("The number is {:d}", 1); // => ~"The number is 1"
+format!("{:?}", ~[3, 4]);         // => ~"~[3, 4]"
+format!("{value}", value=4);      // => ~"4"
+format!("{} {}", 1, 2);           // => ~"1 2"
 ```
 
 From these, you can see that the first argument is a format string. It is
@@ -62,7 +62,7 @@ iterator over the argument. Each time a "next argument" specifier is seen, the
 iterator advances. This leads to behavior like this:
 
 ```rust
-format!("{1} {} {0} {}", 1, 2) // => ~"2 1 1 2"
+format!("{1} {} {0} {}", 1, 2); // => ~"2 1 1 2"
 ```
 
 The internal iterator over the argument has not been advanced by the time the
@@ -89,9 +89,9 @@ identifier '=' expression
 For example, the following `format!` expressions all use named argument:
 
 ```rust
-format!("{argument}", argument = "test")       // => ~"test"
-format!("{name} {}", 1, name = 2)              // => ~"2 1"
-format!("{a:s} {c:d} {b:?}", a="a", b=(), c=3) // => ~"a 3 ()"
+format!("{argument}", argument = "test");       // => ~"test"
+format!("{name} {}", 1, name = 2);              // => ~"2 1"
+format!("{a:s} {c:d} {b:?}", a="a", b=(), c=3); // => ~"a 3 ()"
 ```
 
 It is illegal to put positional parameters (those without names) after arguments
@@ -160,7 +160,11 @@ When implementing a format trait for your own time, you will have to implement a
 method of the signature:
 
 ```rust
+# use std;
+# struct T;
+# trait SomeName<T> {
 fn fmt(value: &T, f: &mut std::fmt::Formatter);
+# }
 ```
 
 Your type will be passed by-reference in `value`, and then the function should
@@ -218,7 +222,7 @@ fn main() {
 There are a number of related macros in the `format!` family. The ones that are
 currently implemented are:
 
-```rust
+```rust,notest
 format!      // described above
 write!       // first argument is a &mut io::Writer, the destination
 writeln!     // same as write but appends a newline
@@ -261,9 +265,13 @@ references information on the stack. Under the hood, all of
 the related macros are implemented in terms of this. First
 off, some example usage is:
 
-```rust
+```rust,ignore
 use std::fmt;
 
+# fn lol<T>() -> T { fail!() }
+# let my_writer: &mut ::std::io::Writer = lol();
+# let my_fn: fn(&fmt::Arguments) = lol();
+
 format_args!(fmt::format, "this returns {}", "~str");
 format_args!(|args| { fmt::write(my_writer, args) }, "some {}", "args");
 format_args!(my_fn, "format {}", "string");
@@ -305,7 +313,7 @@ to reference the string value of the argument which was selected upon. As an
 example:
 
 ```rust
-format!("{0, select, other{#}}", "hello") // => ~"hello"
+format!("{0, select, other{#}}", "hello"); // => ~"hello"
 ```
 
 This example is the equivalent of `{0:s}` essentially.
@@ -585,7 +593,9 @@ pub trait Float { fn fmt(&Self, &mut Formatter); }
 ///
 /// ```rust
 /// use std::fmt;
-/// let w: &mut io::Writer = ...;
+/// use std::io;
+///
+/// let w = &mut io::stdout() as &mut io::Writer;
 /// format_args!(|args| { fmt::write(w, args) }, "Hello, {}!", "world");
 /// ```
 pub fn write(output: &mut io::Writer, args: &Arguments) {
@@ -650,8 +660,9 @@ pub unsafe fn write_unsafe(output: &mut io::Writer,
 ///
 /// ```rust
 /// use std::fmt;
+///
 /// let s = format_args!(fmt::format, "Hello, {}!", "world");
-/// assert_eq!(s, "Hello, world!");
+/// assert_eq!(s, ~"Hello, world!");
 /// ```
 pub fn format(args: &Arguments) -> ~str {
     unsafe { format_unsafe(args.fmt, args.args) }
diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index 537b5de1b4a..03a656ec2c5 100644
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -26,6 +26,9 @@ Some examples of obvious things you might want to do
 * Read lines from stdin
 
     ```rust
+    use std::io::buffered::BufferedReader;
+    use std::io::stdin;
+
     let mut stdin = BufferedReader::new(stdin());
     for line in stdin.lines() {
         print(line);
@@ -35,12 +38,16 @@ Some examples of obvious things you might want to do
 * Read a complete file
 
     ```rust
+    use std::io::File;
+
     let contents = File::open(&Path::new("message.txt")).read_to_end();
     ```
 
 * Write a line to a file
 
     ```rust
+    use std::io::File;
+
     let mut file = File::create(&Path::new("message.txt"));
     file.write(bytes!("hello, file!\n"));
     ```
@@ -48,6 +55,9 @@ Some examples of obvious things you might want to do
 * Iterate over the lines of a file
 
     ```rust
+    use std::io::buffered::BufferedReader;
+    use std::io::File;
+
     let path = Path::new("message.txt");
     let mut file = BufferedReader::new(File::open(&path));
     for line in file.lines() {
@@ -58,6 +68,9 @@ Some examples of obvious things you might want to do
 * Pull the lines of a file into a vector of strings
 
     ```rust
+    use std::io::buffered::BufferedReader;
+    use std::io::File;
+
     let path = Path::new("message.txt");
     let mut file = BufferedReader::new(File::open(&path));
     let lines: ~[~str] = file.lines().collect();
@@ -67,7 +80,10 @@ Some examples of obvious things you might want to do
   XXX This needs more improvement: TcpStream constructor taking &str,
   `write_str` and `write_line` methods.
 
-    ```rust
+    ```rust,ignore
+    use std::io::net::ip::SocketAddr;
+    use std::io::net::tcp::TcpStream;
+
     let addr = from_str::<SocketAddr>("127.0.0.1:8080").unwrap();
     let mut socket = TcpStream::connect(addr).unwrap();
     socket.write(bytes!("GET / HTTP/1.0\n\n"));
diff --git a/src/libstd/io/signal.rs b/src/libstd/io/signal.rs
index c568a19dfa2..00d84e22c25 100644
--- a/src/libstd/io/signal.rs
+++ b/src/libstd/io/signal.rs
@@ -60,11 +60,11 @@ pub enum Signum {
 ///
 /// # Example
 ///
-/// ```rust
+/// ```rust,ignore
 /// use std::io::signal::{Listener, Interrupt};
 ///
 /// let mut listener = Listener::new();
-/// listener.register(signal::Interrupt);
+/// listener.register(Interrupt);
 ///
 /// do spawn {
 ///     loop {
diff --git a/src/libstd/io/timer.rs b/src/libstd/io/timer.rs
index 5fb64ab3d09..9d4a72509e7 100644
--- a/src/libstd/io/timer.rs
+++ b/src/libstd/io/timer.rs
@@ -17,7 +17,7 @@ and create ports which will receive notifications after a period of time.
 
 # Example
 
-```rust
+```rust,ignore
 
 use std::io::Timer;
 
diff --git a/src/libstd/iter.rs b/src/libstd/iter.rs
index f16e9b53929..5ace24dbbee 100644
--- a/src/libstd/iter.rs
+++ b/src/libstd/iter.rs
@@ -218,8 +218,8 @@ pub trait Iterator<A> {
     /// # Example
     ///
     /// ```rust
-    /// let a = [100, 200, 300];
-    /// let mut it = xs.iter().map(|&x|x).peekable();
+    /// let xs = [100, 200, 300];
+    /// let mut it = xs.iter().map(|x| *x).peekable();
     /// assert_eq!(it.peek().unwrap(), &100);
     /// assert_eq!(it.next().unwrap(), 100);
     /// assert_eq!(it.next().unwrap(), 200);
@@ -338,12 +338,14 @@ pub trait Iterator<A> {
     /// # Example
     ///
     /// ```rust
+    /// use std::iter::count;
+    ///
     /// let xs = [2u, 3];
     /// let ys = [0u, 1, 0, 1, 2];
     /// let mut it = xs.iter().flat_map(|&x| count(0u, 1).take(x));
     /// // Check that `it` has the same elements as `ys`
     /// let mut i = 0;
-    /// for x: uint in it {
+    /// for x in it {
     ///     assert_eq!(x, ys[i]);
     ///     i += 1;
     /// }
@@ -366,7 +368,7 @@ pub trait Iterator<A> {
     ///     let mut sum = 0;
     ///     for x in it {
     ///         if x > 5 {
-    ///             break;
+    ///             continue;
     ///         }
     ///         sum += x;
     ///     }
@@ -391,14 +393,16 @@ pub trait Iterator<A> {
     /// # Example
     ///
     /// ```rust
-    ///let xs = [1u, 4, 2, 3, 8, 9, 6];
-    ///let sum = xs.iter()
-    ///            .map(|&x| x)
-    ///            .inspect(|&x| debug!("filtering %u", x))
-    ///            .filter(|&x| x % 2 == 0)
-    ///            .inspect(|&x| debug!("%u made it through", x))
-    ///            .sum();
-    ///println(sum.to_str());
+    /// use std::iter::AdditiveIterator;
+    ///
+    /// let xs = [1u, 4, 2, 3, 8, 9, 6];
+    /// let sum = xs.iter()
+    ///             .map(|&x| x)
+    ///             .inspect(|&x| debug!("filtering {}", x))
+    ///             .filter(|&x| x % 2 == 0)
+    ///             .inspect(|&x| debug!("{} made it through", x))
+    ///             .sum();
+    /// println(sum.to_str());
     /// ```
     #[inline]
     fn inspect<'r>(self, f: 'r |&A|) -> Inspect<'r, A, Self> {
@@ -554,8 +558,8 @@ pub trait Iterator<A> {
     ///
     /// ```rust
     /// let a = [1, 2, 3, 4, 5];
-    /// assert!(a.iter().all(|&x| *x > 0));
-    /// assert!(!a.iter().all(|&x| *x > 2));
+    /// assert!(a.iter().all(|x| *x > 0));
+    /// assert!(!a.iter().all(|x| *x > 2));
     /// ```
     #[inline]
     fn all(&mut self, f: |A| -> bool) -> bool {
@@ -571,8 +575,8 @@ pub trait Iterator<A> {
     /// ```rust
     /// let a = [1, 2, 3, 4, 5];
     /// let mut it = a.iter();
-    /// assert!(it.any(|&x| *x == 3));
-    /// assert!(!it.any(|&x| *x == 3));
+    /// assert!(it.any(|x| *x == 3));
+    /// assert!(!it.any(|x| *x == 3));
     /// ```
     #[inline]
     fn any(&mut self, f: |A| -> bool) -> bool {
@@ -618,7 +622,7 @@ pub trait Iterator<A> {
     /// # Example
     ///
     /// ```rust
-    /// let xs = [-3, 0, 1, 5, -10];
+    /// let xs = [-3i, 0, 1, 5, -10];
     /// assert_eq!(*xs.iter().max_by(|x| x.abs()).unwrap(), -10);
     /// ```
     #[inline]
@@ -642,7 +646,7 @@ pub trait Iterator<A> {
     /// # Example
     ///
     /// ```rust
-    /// let xs = [-3, 0, 1, 5, -10];
+    /// let xs = [-3i, 0, 1, 5, -10];
     /// assert_eq!(*xs.iter().min_by(|x| x.abs()).unwrap(), 0);
     /// ```
     #[inline]
@@ -811,6 +815,8 @@ pub trait AdditiveIterator<A> {
     /// # Example
     ///
     /// ```rust
+    /// use std::iter::AdditiveIterator;
+    ///
     /// let a = [1, 2, 3, 4, 5];
     /// let mut it = a.iter().map(|&x| x);
     /// assert!(it.sum() == 15);
@@ -834,7 +840,7 @@ pub trait MultiplicativeIterator<A> {
     /// # Example
     ///
     /// ```rust
-    /// use std::iter::count;
+    /// use std::iter::{count, MultiplicativeIterator};
     ///
     /// fn factorial(n: uint) -> uint {
     ///     count(1u, 1).take_while(|&i| i <= n).product()
@@ -907,6 +913,8 @@ pub trait ClonableIterator {
     /// # Example
     ///
     /// ```rust
+    /// use std::iter::{ClonableIterator, count};
+    ///
     /// let a = count(1,1).take(1);
     /// let mut cy = a.cycle();
     /// assert_eq!(cy.next(), Some(1));
diff --git a/src/libstd/local_data.rs b/src/libstd/local_data.rs
index 69f1bfe9395..652aa4d8198 100644
--- a/src/libstd/local_data.rs
+++ b/src/libstd/local_data.rs
@@ -29,10 +29,10 @@ local_data_key!(key_int: int)
 local_data_key!(key_vector: ~[int])
 
 local_data::set(key_int, 3);
-local_data::get(key_int, |opt| assert_eq!(opt, Some(&3)));
+local_data::get(key_int, |opt| assert_eq!(opt.map(|x| *x), Some(3)));
 
 local_data::set(key_vector, ~[4]);
-local_data::get(key_vector, |opt| assert_eq!(opt, Some(&~[4])));
+local_data::get(key_vector, |opt| assert_eq!(*opt.unwrap(), ~[4]));
  ```
 
 */
diff --git a/src/libstd/logging.rs b/src/libstd/logging.rs
index 1605dcebf1a..59e57a8680d 100644
--- a/src/libstd/logging.rs
+++ b/src/libstd/logging.rs
@@ -78,7 +78,7 @@ error,hello=warn     // turn on global error logging and also warn for hello
 
 Each of these macros will expand to code similar to:
 
-```rust
+```rust,notest
 if log_level <= my_module_log_level() {
     ::std::logging::log(log_level, format!(...));
 }
diff --git a/src/libstd/num/f32.rs b/src/libstd/num/f32.rs
index 4eef3323403..2cb7d527618 100644
--- a/src/libstd/num/f32.rs
+++ b/src/libstd/num/f32.rs
@@ -339,7 +339,8 @@ impl Round for f32 {
     /// The fractional part of the number, satisfying:
     ///
     /// ```rust
-    /// assert!(x == trunc(x) + fract(x))
+    /// let x = 1.65f32;
+    /// assert!(x == x.trunc() + x.fract())
     /// ```
     ///
     #[inline]
diff --git a/src/libstd/num/f64.rs b/src/libstd/num/f64.rs
index 1668019409e..1f01c26ad76 100644
--- a/src/libstd/num/f64.rs
+++ b/src/libstd/num/f64.rs
@@ -357,7 +357,8 @@ impl Round for f64 {
     /// The fractional part of the number, satisfying:
     ///
     /// ```rust
-    /// assert!(x == trunc(x) + fract(x))
+    /// let x = 1.65f64;
+    /// assert!(x == x.trunc() + x.fract())
     /// ```
     ///
     #[inline]
diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs
index c8c2ea8af81..0f81a5faac8 100644
--- a/src/libstd/num/mod.rs
+++ b/src/libstd/num/mod.rs
@@ -101,8 +101,7 @@ pub trait Unsigned: Num {}
 /// Times trait
 ///
 /// ```rust
-/// use num::Times;
-/// let ten = 10 as uint;
+/// let ten = 10u;
 /// let mut accum = 0;
 /// ten.times(|| { accum += 1; })
 /// ```
@@ -176,10 +175,10 @@ pub trait Round {
     /// # Example
     ///
     /// ```rust
-    /// assert_approx_eq!(1.3f32.round(), 1.0);
-    /// assert_approx_eq!((-1.3f32).round(), -1.0);
-    /// assert_approx_eq!(1.5f32.round(), 1.0);
-    /// assert_approx_eq!((-1.5f32).round(), -1.0);
+    /// assert_approx_eq!(1.3f32.trunc(), 1.0);
+    /// assert_approx_eq!((-1.3f32).trunc(), -1.0);
+    /// assert_approx_eq!(1.5f32.trunc(), 1.0);
+    /// assert_approx_eq!((-1.5f32).trunc(), -1.0);
     /// ```
     fn trunc(&self) -> Self;
 
@@ -188,10 +187,10 @@ pub trait Round {
     /// # Example
     ///
     /// ```rust
-    /// assert_approx_eq!(1.3f32.round(), 0.3);
-    /// assert_approx_eq!((-1.3f32).round(), -0.3);
-    /// assert_approx_eq!(1.5f32.round(), 0.5);
-    /// assert_approx_eq!((-1.5f32).round(), -0.5);
+    /// assert_approx_eq!(1.3f32.fract(), 0.3);
+    /// assert_approx_eq!((-1.3f32).fract(), -0.3);
+    /// assert_approx_eq!(1.5f32.fract(), 0.5);
+    /// assert_approx_eq!((-1.5f32).fract(), -0.5);
     /// ```
     fn fract(&self) -> Self;
 }
@@ -225,7 +224,9 @@ pub trait Algebraic {
 /// # Example
 ///
 /// ```rust
-/// let sixteen: float = num::pow(2.0, 4.0);
+/// use std::num;
+///
+/// let sixteen: f64 = num::pow(2.0, 4.0);
 /// assert_eq!(sixteen, 16.0);
 /// ```
 #[inline(always)] pub fn pow<T: Algebraic>(value: T, n: T) -> T { value.pow(&n) }
@@ -266,6 +267,8 @@ pub trait Trigonometric {
     /// # Example
     ///
     /// ```rust
+    /// use std::f32;
+    ///
     /// let y = 3f32.sqrt();
     /// let x = 1f32;
     /// assert_approx_eq!(y.atan2(&x), f32::consts::PI / 3f32);
diff --git a/src/libstd/path/mod.rs b/src/libstd/path/mod.rs
index 53948dc8309..6488595ea4f 100644
--- a/src/libstd/path/mod.rs
+++ b/src/libstd/path/mod.rs
@@ -54,12 +54,11 @@ actually operates on the path; it is only intended for display.
 
 ```rust
 let mut path = Path::new("/tmp/path");
-debug!("path: {}", path.display());
+println!("path: {}", path.display());
 path.set_filename("foo");
 path.push("bar");
-debug!("new path: {}", path.display());
-let b = std::os::path_exists(&path);
-debug!("path exists: {}", b);
+println!("new path: {}", path.display());
+println!("path exists: {}", path.exists());
 ```
 
 */
diff --git a/src/libstd/rand/distributions/gamma.rs b/src/libstd/rand/distributions/gamma.rs
index ae7ff99af92..36acae9133c 100644
--- a/src/libstd/rand/distributions/gamma.rs
+++ b/src/libstd/rand/distributions/gamma.rs
@@ -39,7 +39,7 @@ use num;
 ///
 /// fn main() {
 ///     let gamma = Gamma::new(2.0, 5.0);
-///     let v = gamma.ind_sample(rand::task_rng());
+///     let v = gamma.ind_sample(&mut rand::task_rng());
 ///     println!("{} is from a Gamma(2, 5) distribution", v);
 /// }
 /// ```
diff --git a/src/libstd/rand/distributions/mod.rs b/src/libstd/rand/distributions/mod.rs
index dd882f051d3..f13f840df40 100644
--- a/src/libstd/rand/distributions/mod.rs
+++ b/src/libstd/rand/distributions/mod.rs
@@ -98,10 +98,10 @@ pub struct Weighted<T> {
 ///     let wc = WeightedChoice::new(~[Weighted { weight: 2, item: 'a' },
 ///                                    Weighted { weight: 4, item: 'b' },
 ///                                    Weighted { weight: 1, item: 'c' }]);
-///     let rng = rand::task_rng();
+///     let mut rng = rand::task_rng();
 ///     for _ in range(0, 16) {
 ///          // on average prints 'a' 4 times, 'b' 8 and 'c' twice.
-///          println!("{}", wc.ind_sample(rng));
+///          println!("{}", wc.ind_sample(&mut rng));
 ///     }
 /// }
 /// ```
diff --git a/src/libstd/rand/distributions/normal.rs b/src/libstd/rand/distributions/normal.rs
index a779f4f6066..8b769c113c9 100644
--- a/src/libstd/rand/distributions/normal.rs
+++ b/src/libstd/rand/distributions/normal.rs
@@ -123,7 +123,7 @@ impl IndependentSample<f64> for Normal {
 /// fn main() {
 ///     // mean 2, standard deviation 3
 ///     let log_normal = LogNormal::new(2.0, 3.0);
-///     let v = normal.ind_sample(&mut rand::task_rng());
+///     let v = log_normal.ind_sample(&mut rand::task_rng());
 ///     println!("{} is from an ln N(2, 9) distribution", v)
 /// }
 /// ```
diff --git a/src/libstd/rand/distributions/range.rs b/src/libstd/rand/distributions/range.rs
index db9cefa4d79..fc6cdde162d 100644
--- a/src/libstd/rand/distributions/range.rs
+++ b/src/libstd/rand/distributions/range.rs
@@ -39,10 +39,10 @@ use rand::distributions::{Sample, IndependentSample};
 ///
 /// fn main() {
 ///     let between = Range::new(10u, 10000u);
-///     let rng = rand::task_rng();
+///     let mut rng = rand::task_rng();
 ///     let mut sum = 0;
 ///     for _ in range(0, 1000) {
-///         sum += between.ind_sample(rng);
+///         sum += between.ind_sample(&mut rng);
 ///     }
 ///     println!("{}", sum);
 /// }
diff --git a/src/libstd/rand/mod.rs b/src/libstd/rand/mod.rs
index e3929501e19..76bb6723a2e 100644
--- a/src/libstd/rand/mod.rs
+++ b/src/libstd/rand/mod.rs
@@ -64,7 +64,7 @@ use std::rand;
 
 fn main () {
     let tuple_ptr = rand::random::<~(f64, char)>();
-    println!(tuple_ptr)
+    println!("{:?}", tuple_ptr)
 }
  ```
 */
@@ -227,7 +227,7 @@ pub trait Rng {
     ///    let mut rng = rand::task_rng();
     ///    let n: uint = rng.gen_range(0u, 10);
     ///    println!("{}", n);
-    ///    let m: float = rng.gen_range(-40.0, 1.3e5);
+    ///    let m: f64 = rng.gen_range(-40.0, 1.3e5);
     ///    println!("{}", m);
     /// }
     /// ```
@@ -292,8 +292,10 @@ pub trait Rng {
     /// use std::rand::Rng;
     ///
     /// fn main() {
-    ///     println!("{:?}", rand::task_rng().choose_option([1,2,4,8,16,32]));
-    ///     println!("{:?}", rand::task_rng().choose_option([]));
+    ///     let choices = [1, 2, 4, 8, 16, 32];
+    ///     let mut rng = rand::task_rng();
+    ///     println!("{:?}", rng.choose_option(choices));
+    ///     println!("{:?}", rng.choose_option(choices.slice_to(0)));
     /// }
     /// ```
     fn choose_option<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T> {
@@ -388,11 +390,10 @@ pub trait SeedableRng<Seed>: Rng {
     /// # Example
     ///
     /// ```rust
-    /// use std::rand;
-    /// use std::rand::Rng;
+    /// use std::rand::{Rng, SeedableRng, StdRng};
     ///
     /// fn main() {
-    ///     let mut rng: rand::StdRng = rand::SeedableRng::from_seed(&[1, 2, 3, 4]);
+    ///     let mut rng: StdRng = SeedableRng::from_seed(&[1, 2, 3, 4]);
     ///     println!("{}", rng.gen::<f64>());
     ///     rng.reseed([5, 6, 7, 8]);
     ///     println!("{}", rng.gen::<f64>());
diff --git a/src/libstd/str.rs b/src/libstd/str.rs
index 5f98a34520c..2f5ef932a18 100644
--- a/src/libstd/str.rs
+++ b/src/libstd/str.rs
@@ -1458,10 +1458,10 @@ pub trait StrSlice<'a> {
     /// let v: ~[(uint, uint)] = "abcXXXabcYYYabc".match_indices("abc").collect();
     /// assert_eq!(v, ~[(0,3), (6,9), (12,15)]);
     ///
-    /// let v: ~[(uint, uint)] = "1abcabc2".split_str("abc").collect();
+    /// let v: ~[(uint, uint)] = "1abcabc2".match_indices("abc").collect();
     /// assert_eq!(v, ~[(1,4), (4,7)]);
     ///
-    /// let v: ~[(uint, uint)] = "ababa".split_str("aba").collect();
+    /// let v: ~[(uint, uint)] = "ababa".match_indices("aba").collect();
     /// assert_eq!(v, ~[(0, 3)]); // only the first `aba`
     /// ```
     fn match_indices(&self, sep: &'a str) -> MatchesIndexIterator<'a>;
@@ -1536,7 +1536,7 @@ pub trait StrSlice<'a> {
     /// assert!(" \t\n".is_whitespace());
     /// assert!("".is_whitespace());
     ///
-    /// assert!( !"abc.is_whitespace());
+    /// assert!( !"abc".is_whitespace());
     /// ```
     fn is_whitespace(&self) -> bool;
 
@@ -1606,7 +1606,7 @@ pub trait StrSlice<'a> {
     /// let s = "Löwe 老虎 Léopard";
     /// assert_eq!(s.slice(0, 1), "L");
     ///
-    /// assert_eq!(s.slice(1, 9), "öwe 老"));
+    /// assert_eq!(s.slice(1, 9), "öwe 老");
     ///
     /// // these will fail:
     /// // byte 2 lies within `ö`:
@@ -1808,6 +1808,8 @@ pub trait StrSlice<'a> {
     /// `.char_indices`.
     ///
     /// ```rust
+    /// use std::str::CharRange;
+    ///
     /// let s = "中华Việt Nam";
     /// let mut i = 0u;
     /// while i < s.len() {
@@ -1949,11 +1951,11 @@ pub trait StrSlice<'a> {
     ///
     /// ```rust
     /// let s = "Löwe 老虎 Léopard";
-    /// let (c, s1) = s.shift_slice_char();
+    /// let (c, s1) = s.slice_shift_char();
     /// assert_eq!(c, 'L');
     /// assert_eq!(s1, "öwe 老虎 Léopard");
     ///
-    /// let (c, s2) = s1.shift_slice_char();
+    /// let (c, s2) = s1.slice_shift_char();
     /// assert_eq!(c, 'ö');
     /// assert_eq!(s2, "we 老虎 Léopard");
     /// ```
diff --git a/src/libstd/vec.rs b/src/libstd/vec.rs
index 487f6749e3e..97d4c2f6d1b 100644
--- a/src/libstd/vec.rs
+++ b/src/libstd/vec.rs
@@ -2174,12 +2174,12 @@ pub trait MutableVector<'a, T> {
     /// # Example
     ///
     /// ```rust
-    /// let mut v = [5, 4, 1, 3, 2];
-    /// v.sort(|a, b| a.cmp(b));
+    /// let mut v = [5i, 4, 1, 3, 2];
+    /// v.sort_by(|a, b| a.cmp(b));
     /// assert_eq!(v, [1, 2, 3, 4, 5]);
     ///
     /// // reverse sorting
-    /// v.sort(|a, b| b.cmp(a));
+    /// v.sort_by(|a, b| b.cmp(a));
     /// assert_eq!(v, [5, 4, 3, 2, 1]);
     /// ```
     fn sort_by(self, compare: |&T, &T| -> Ordering);
@@ -2395,8 +2395,6 @@ pub trait MutableTotalOrdVector<T> {
     /// # Example
     ///
     /// ```rust
-    /// use std::vec;
-    ///
     /// let mut v = [-5, 4, 1, -3, 2];
     ///
     /// v.sort();