API Docs: net

[steveklabnik]

Part of #29329

http://doc.rust-lang.org/std/net/

Here's what needs to be done to close out this issue:

• the module documentation is very tiny and needs expanded.
• ParseError needs to link to where it comes from and have examples.
• Incoming should use the standard iterator boilerplate and move its semantics into the method docs.
• Ipv4Addr needs better top-level docs and should link to IpAddr
• many places in these docs should say "IETF RFC" rather than "RFC", as we have Rust RFCs as well.
• Ipv6Addr same as Ipv4Addr.
• SocketAddrV4 has poor top-level docs and needs to have a defined summary/explanation split. Its methods are okay, but very short. It needs to link to SocketAddr.
• SocketAddrV6 same
• TcpListener's docs don't really say what it is.
• TcpStream's the same.
• UpdSocket is the same.
• IpAddr should link to an IETF RFC
• Shutdown should use the standard boilerplate
• SocketAddr has very short docs.
• ToSocketAddrs needs a lot of links.

[apoelstra]

Hi,

https://doc.rust-lang.org/std/net/struct.Incoming.html

Says that the Incoming iterator will return an infinite list of incoming connections. In fact, it may error out (for example if the system runs out of file descriptors) and return an infinite list of errors, with no delays in between. A naive "log and retry" loop may become a spinloop in this case, pegging the CPU and/or filling log space.

[steveklabnik]

I am happy to mentor anyone who wants to tackle this issue.

[chordowl]

I'm gonna try to tackle (parts of?) the docs for TcpListener & TcpStream, especially with regard to #40322 since I've been digging information for that up anyway; I'll probably grab some low-hanging fruit beforehand though.