auto merge of #13458 : huonw/rust/doc-signatures, r=alexcrichton

Add more type signatures to the docs; tweak a few of them.

Someone reading the docs won't know what the types of various things
are, so this adds them in a few meaningful places to help with
comprehension.

cc #13423.

src/libstd/fmt/mod.rs

@@ -276,16 +276,22 @@ 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:
 
-```ignore
+```
 use std::fmt;
+use std::io;
 
-# fn lol<T>() -> T { fail!() }
-# let my_writer: &mut ::std::io::Writer = lol();
-# let my_fn: fn(&fmt::Arguments) = lol();
-
+# #[allow(unused_must_use)]
+# fn main() {
 format_args!(fmt::format, "this returns {}", "~str");
-format_args!(|args| { fmt::write(my_writer, args) }, "some {}", "args");
-format_args!(my_fn, "format {}", "string");
+
+let some_writer: &mut io::Writer = &mut io::stdout();
+format_args!(|args| { fmt::write(some_writer, args) }, "print with a {}", "closure");
+
+fn my_fmt_fn(args: &fmt::Arguments) {
+    fmt::write(&mut io::stdout(), args);
+}
+format_args!(my_fmt_fn, "or a {} too", "function");
+# }
 ```
 
 The first argument of the `format_args!` macro is a function (or closure) which

src/libstd/io/mod.rs

@@ -97,8 +97,8 @@ Some examples of obvious things you might want to do
     ```rust
     # fn main() { }
     # fn foo() {
-    # #[allow(unused_must_use, dead_code)];
-    use std::io::net::tcp::TcpListener;
+    # #![allow(dead_code)]
+    use std::io::{TcpListener, TcpStream};
     use std::io::net::ip::{Ipv4Addr, SocketAddr};
     use std::io::{Acceptor, Listener};
 
@@ -108,12 +108,19 @@ Some examples of obvious things you might want to do
     // bind the listener to the specified address
     let mut acceptor = listener.listen();
 
-    // accept connections and process them
-    # fn handle_client<T>(_: T) {}
+    fn handle_client(mut stream: TcpStream) {
+        // ...
+    # &mut stream; // silence unused mutability/variable warning
+    }
+    // accept connections and process them, spawning a new tasks for each one
     for stream in acceptor.incoming() {
-        spawn(proc() {
-            handle_client(stream);
-        });
+        match stream {
+            Err(e) => { /* connection failed */ }
+            Ok(stream) => spawn(proc() {
+                // connection succeeded
+                handle_client(stream)
+            })
+        }
     }
 
     // close the socket server

src/libstd/io/net/tcp.rs

@@ -100,10 +100,10 @@ impl Writer for TcpStream {
 /// # Example
 ///
 /// ```rust
-/// # fn main() {}
+/// # fn main() { }
 /// # fn foo() {
-/// # #[allow(unused_must_use, dead_code)];
-/// use std::io::net::tcp::TcpListener;
+/// # #![allow(dead_code)]
+/// use std::io::{TcpListener, TcpStream};
 /// use std::io::net::ip::{Ipv4Addr, SocketAddr};
 /// use std::io::{Acceptor, Listener};
 ///
@@ -113,12 +113,19 @@ impl Writer for TcpStream {
 /// // bind the listener to the specified address
 /// let mut acceptor = listener.listen();
 ///
-/// // accept connections and process them
-/// # fn handle_client<T>(_: T) {}
+/// fn handle_client(mut stream: TcpStream) {
+///     // ...
+/// # &mut stream; // silence unused mutability/variable warning
+/// }
+/// // accept connections and process them, spawning a new tasks for each one
 /// for stream in acceptor.incoming() {
-///     spawn(proc() {
-///         handle_client(stream);
-///     });
+///     match stream {
+///         Err(e) => { /* connection failed */ }
+///         Ok(stream) => spawn(proc() {
+///             // connection succeeded
+///             handle_client(stream)
+///         })
+///     }
 /// }
 ///
 /// // close the socket server
@@ -728,4 +735,3 @@ mod test {
         assert_eq!(s.read_to_end(), Ok(vec!(1)));
     })
 }
-

src/libstd/sync/atomics.rs

@@ -157,7 +157,7 @@ pub struct AtomicOption<T> {
 ///
 /// Rust's memory orderings are the same as in C++[1].
 ///
-/// [1]: http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync
+/// 1: http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync
 pub enum Ordering {
     /// No ordering constraints, only atomic operations
     Relaxed,

src/libstd/unstable/finally.rs

@@ -21,12 +21,11 @@ also be used. See that function for more details.
 
 ```
 use std::unstable::finally::Finally;
-# fn always_run_this() {}
 
 (|| {
     // ...
 }).finally(|| {
-    always_run_this();
+    // this code is always run
 })
 ```
 */
@@ -158,4 +157,3 @@ fn test_compact() {
     do_some_fallible_work.finally(
         but_always_run_this_function);
 }
-