Evaluate # fn in docs

I searched for times when we were hiding functions with # in the documentation,
and fixed them to not use it unless neccesary.

I also made random improvements whenever I changed something. For example,
I changed Example to Examples, for consistency.

Fixes #13423

7 files changed, 36 insertions, 50 deletions

diff --git a/src/libstd/fmt.rs b/src/libstd/fmt.rs
index 907925e93d3..36afa0956d2 100644
--- a/src/libstd/fmt.rs
+++ b/src/libstd/fmt.rs
@@ -26,15 +26,13 @@
 //!
 //! Some examples of the `format!` extension are:
 //!
-//! ```rust
-//! # fn main() {
+//! ```
 //! format!("Hello");                  // => "Hello"
 //! format!("Hello, {}!", "world");    // => "Hello, world!"
 //! format!("The number is {}", 1i);   // => "The number is 1"
 //! format!("{:?}", (3i, 4i));         // => "(3i, 4i)"
 //! format!("{value}", value=4i);      // => "4"
 //! format!("{} {}", 1i, 2u);          // => "1 2"
-//! # }
 //! ```
 //!
 //! From these, you can see that the first argument is a format string. It is
@@ -83,12 +81,10 @@
 //!
 //! For example, the following `format!` expressions all use named argument:
 //!
-//! ```rust
-//! # fn main() {
+//! ```
 //! format!("{argument}", argument = "test");   // => "test"
 //! format!("{name} {}", 1i, name = 2i);        // => "2 1"
 //! format!("{a} {c} {b}", a="a", b='b', c=3i);  // => "a 3 b"
-//! # }
 //! ```
 //!
 //! It is illegal to put positional parameters (those without names) after
@@ -288,8 +284,6 @@
 //! use std::fmt;
 //! use std::io;
 //!
-//! # #[allow(unused_must_use)]
-//! # fn main() {
 //! fmt::format(format_args!("this returns {}", "String"));
 //!
 //! let some_writer: &mut io::Writer = &mut io::stdout();
@@ -299,7 +293,6 @@
 //!     write!(&mut io::stdout(), "{}", args);
 //! }
 //! my_fmt_fn(format_args!("or a {} too", "function"));
-//! # }
 //! ```
 //!
 //! The result of the `format_args!` macro is a value of type `fmt::Arguments`.
diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index bab4dafd090..e2b71cd43af 100644
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -934,16 +934,15 @@ unsafe fn slice_vec_capacity<'a, T>(v: &'a mut Vec<T>, start: uint, end: uint) -
 /// A `RefReader` is a struct implementing `Reader` which contains a reference
 /// to another reader. This is often useful when composing streams.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
-/// # fn main() {}
-/// # fn process_input<R: Reader>(r: R) {}
-/// # fn foo() {
 /// use std::io;
 /// use std::io::ByRefReader;
 /// use std::io::util::LimitReader;
 ///
+/// fn process_input<R: Reader>(r: R) {}
+///
 /// let mut stream = io::stdin();
 ///
 /// // Only allow the function to process at most one kilobyte of input
@@ -953,8 +952,6 @@ unsafe fn slice_vec_capacity<'a, T>(v: &'a mut Vec<T>, start: uint, end: uint) -
 /// }
 ///
 /// // 'stream' is still available for use here
-///
-/// # }
 /// ```
 pub struct RefReader<'a, R:'a> {
     /// The underlying reader which this is referencing
@@ -1269,12 +1266,11 @@ impl<'a> Writer for &'a mut (Writer+'a) {
 /// # Example
 ///
 /// ```
-/// # fn main() {}
-/// # fn process_input<R: Reader>(r: R) {}
-/// # fn foo () {
 /// use std::io::util::TeeReader;
 /// use std::io::{stdin, ByRefWriter};
 ///
+/// fn process_input<R: Reader>(r: R) {}
+///
 /// let mut output = Vec::new();
 ///
 /// {
@@ -1285,7 +1281,6 @@ impl<'a> Writer for &'a mut (Writer+'a) {
 /// }
 ///
 /// println!("input processed: {:?}", output);
-/// # }
 /// ```
 pub struct RefWriter<'a, W:'a> {
     /// The underlying writer which this is referencing
@@ -1705,19 +1700,19 @@ pub enum FileType {
 /// A structure used to describe metadata information about a file. This
 /// structure is created through the `stat` method on a `Path`.
 ///
-/// # Example
+/// # Examples
+///
+/// ```no_run
+/// # #![allow(unstable)]
+///
+/// use std::io::fs::PathExtensions;
 ///
-/// ```
-/// # use std::io::fs::PathExtensions;
-/// # fn main() {}
-/// # fn foo() {
 /// let info = match Path::new("foo.txt").stat() {
 ///     Ok(stat) => stat,
 ///     Err(e) => panic!("couldn't read foo.txt: {}", e),
 /// };
 ///
 /// println!("byte size: {}", info.size);
-/// # }
 /// ```
 #[derive(Copy, Hash)]
 pub struct FileStat {
diff --git a/src/libstd/io/net/pipe.rs b/src/libstd/io/net/pipe.rs
index 42d9fff6d15..61d164d21e3 100644
--- a/src/libstd/io/net/pipe.rs
+++ b/src/libstd/io/net/pipe.rs
@@ -168,9 +168,7 @@ impl UnixListener {
     /// # Example
     ///
     /// ```
-    /// # fn main() {}
     /// # fn foo() {
-    /// # #![allow(unused_must_use)]
     /// use std::io::net::pipe::UnixListener;
     /// use std::io::{Listener, Acceptor};
     ///
diff --git a/src/libstd/io/net/tcp.rs b/src/libstd/io/net/tcp.rs
index 6a3f5fcb2c6..4978085fa4f 100644
--- a/src/libstd/io/net/tcp.rs
+++ b/src/libstd/io/net/tcp.rs
@@ -272,12 +272,10 @@ impl sys_common::AsInner<TcpStreamImp> for TcpStream {
 /// A structure representing a socket server. This listener is used to create a
 /// `TcpAcceptor` which can be used to accept sockets on a local port.
 ///
-/// # Example
+/// # Examples
 ///
-/// ```rust
-/// # fn main() { }
+/// ```
 /// # fn foo() {
-/// # #![allow(dead_code)]
 /// use std::io::{TcpListener, TcpStream};
 /// use std::io::{Acceptor, Listener};
 /// use std::thread::Thread;
diff --git a/src/libstd/io/timer.rs b/src/libstd/io/timer.rs
index 8a0445be471..844a97dea2d 100644
--- a/src/libstd/io/timer.rs
+++ b/src/libstd/io/timer.rs
@@ -27,10 +27,9 @@ use sys::timer::Timer as TimerImp;
 /// period of time. Handles to this timer can also be created in the form of
 /// receivers which will receive notifications over time.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
-/// # fn main() {}
 /// # fn foo() {
 /// use std::io::Timer;
 /// use std::time::Duration;
@@ -54,7 +53,6 @@ use sys::timer::Timer as TimerImp;
 /// the `io::timer` module.
 ///
 /// ```
-/// # fn main() {}
 /// # fn foo() {
 /// use std::io::timer;
 /// use std::time::Duration;
diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs
index a420c841d25..5795b4c38c6 100644
--- a/src/libstd/macros.rs
+++ b/src/libstd/macros.rs
@@ -122,16 +122,18 @@ macro_rules! try {
 /// receivers. It places no restrictions on the types of receivers given to
 /// this macro, this can be viewed as a heterogeneous select.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use std::thread::Thread;
-/// use std::sync::mpsc::channel;
+/// use std::sync::mpsc;
+///
+/// // two placeholder functions for now
+/// fn long_running_task() {}
+/// fn calculate_the_answer() -> u32 { 42 }
 ///
-/// let (tx1, rx1) = channel();
-/// let (tx2, rx2) = channel();
-/// # fn long_running_task() {}
-/// # fn calculate_the_answer() -> int { 42i }
+/// let (tx1, rx1) = mpsc::channel();
+/// let (tx2, rx2) = mpsc::channel();
 ///
 /// Thread::spawn(move|| { long_running_task(); tx1.send(()).unwrap(); });
 /// Thread::spawn(move|| { tx2.send(calculate_the_answer()).unwrap(); });
@@ -251,17 +253,15 @@ pub mod builtin {
     /// statement or expression position, meaning this macro may be difficult to
     /// use in some situations.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// #![feature(concat_idents)]
     ///
-    /// # fn main() {
-    /// fn foobar() -> int { 23 }
+    /// fn foobar() -> u32 { 23 }
     ///
     /// let f = concat_idents!(foo, bar);
     /// println!("{}", f());
-    /// # }
     /// ```
     #[macro_export]
     macro_rules! concat_idents {
diff --git a/src/libstd/sync/future.rs b/src/libstd/sync/future.rs
index 568c24446e7..36bbc5ff5b4 100644
--- a/src/libstd/sync/future.rs
+++ b/src/libstd/sync/future.rs
@@ -11,14 +11,18 @@
 //! A type representing values that may be computed concurrently and operations
 //! for working with them.
 //!
-//! # Example
+//! # Examples
 //!
-//! ```rust
+//! ```
 //! use std::sync::Future;
-//! # fn fib(n: uint) -> uint {42};
-//! # fn make_a_sandwich() {};
-//! let mut delayed_fib = Future::spawn(move|| { fib(5000) });
-//! make_a_sandwich();
+//!
+//! // a fake, for now
+//! fn fib(n: u32) -> u32 { 42 };
+//!
+//! let mut delayed_fib = Future::spawn(move || fib(5000));
+//!
+//! // do stuff...
+//!
 //! println!("fib(5000) = {}", delayed_fib.get())
 //! ```