std: Fix all code examples

Author: alexcrichton

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

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]);
  * ```
  */

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();
 //! ```

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)];
 

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 };

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) }

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,19 +38,26 @@ 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"));
     ```
 
 * 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"));

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 {

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;