Write (at least) type signatures of placeholder functions in docs

[huonw]

E.g. TcpListener has

use std::io::net::tcp::TcpListener;
use std::io::net::ip::{Ipv4Addr, SocketAddr};
use std::io::{Acceptor, Listener};

let addr = SocketAddr { ip: Ipv4Addr(127, 0, 0, 1), port: 80 };
let listener = TcpListener::bind(addr);

// bind the listener to the specified address
let mut acceptor = listener.listen();

// accept connections and process them
for stream in acceptor.incoming() {
    spawn(proc() {
        handle_client(stream);
    });
}

// close the socket server
drop(acceptor);

but the handle_client function isn't defined, and it's not particularly obvious what it should be, having something like

fn handle_client(mut stream: TcpStream) {
     // ...
}

in the code too would make it easier to interpret. (I'm sure this isn't the only example of this.)

[ghost]

Prevents errors

for stream in acceptor.incoming() {
     match stream {
          Err(_) => continue,
          Ok(socket) => spawn(proc() { handle_client(socket); }
     }
}

[ghost]

Example extra (HTTP Server): https://gist.github.com/IrvMG/10617371

[steveklabnik]

@huonw given that your PR in this specific case got merged, is this still valid? I mean, there may be other cases, but how will we know when this issue is done?

[huonw]

Maybe we could just do a quick pass over the docs to try to remove any remaining current instances (e.g. git grep '# .*fn' would probably pick up most instances).

[steveklabnik]

👍

[steveklabnik]

$ git grep "# .*fn" | wc -l
368

Whew!