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

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 {

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

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;

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;