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.

2 files changed, 29 insertions, 16 deletions

diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index f384000896c..ccff857f606 100644
--- a/src/libstd/io/mod.rs
+++ b/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
diff --git a/src/libstd/io/net/tcp.rs b/src/libstd/io/net/tcp.rs
index 02c061c54dd..2253b22796f 100644
--- a/src/libstd/io/net/tcp.rs
+++ b/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)));
     })
 }
-