Rustdoc examples for mio::net methods

[dtolnay]

Per the C-EXAMPLE guideline.

Keep in mind that the purpose of an example is not always to show how to use the item. Users can be expected to understand the syntax of how to invoke a method or match on an enum. Rather, an example is often intended to show why someone would want to use the item.

---

• TcpListener::bind
• TcpListener::from_listener
• TcpListener::accept
• TcpListener::local_addr
• TcpListener::try_clone
• TcpListener::set_ttl
• TcpListener::ttl
• TcpListener::set_only_v6
• TcpListener::only_v6
• TcpListener::take_error

---

• TcpStream::connect
• TcpStream::connect_stream
• TcpStream::from_stream
• TcpStream::peer_addr
• TcpStream::local_addr
• TcpStream::try_clone
• TcpStream::shutdown
• TcpStream::set_nodelay
• TcpStream::nodelay
• TcpStream::set_recv_buffer_size
• TcpStream::recv_buffer_size
• TcpStream::set_send_buffer_size
• TcpStream::send_buffer_size
• TcpStream::set_keepalive
• TcpStream::keepalive
• TcpStream::set_ttl
• TcpStream::ttl
• TcpStream::set_only_v6
• TcpStream::only_v6
• TcpStream::set_linger
• TcpStream::linger
• TcpStream::take_error
• TcpStream::read_bufs
• TcpStream::write_bufs

---

• UdpSocket::bind
• UdpSocket::from_socket
• UdpSocket::local_addr
• UdpSocket::try_clone
• UdpSocket::send_to
• UdpSocket::recv_from
• UdpSocket::send
• UdpSocket::recv
• UdpSocket::connect
• UdpSocket::broadcast
• UdpSocket::set_broadcast
• UdpSocket::multicast_loop_v4
• UdpSocket::set_multicast_loop_v4
• UdpSocket::multicast_ttl_v4
• UdpSocket::set_multicast_ttl_v4
• UdpSocket::multicast_loop_v6
• UdpSocket::set_mulitcast_loop_v6
• UdpSocket::ttl
• UdpSocket::set_ttl
• UdpSocket::join_multicast_v4
• UdpSocket::join_multicast_v6
• UdpSocket::leave_multicast_v4
• UdpSocket::leave_multicast_v6
• UdpSocket::set_only_v6
• UdpSocket::only_v6
• UdpSocket::take_error

[lanedraex]

Hey, I would like to help out with the examples.

Should they look like std::net::UdpSocket or be more detailed when possible?

Taking mio::net::UdpSocket::try_clone() as an example, should it look like:

// Sample 1
let socket = UdpSocket::bind(&"127.0.0.1:7777".parse()?)?;
let cloned = socket.try_clone();

or should it look like:

// Sample 2
let socket = UdpSocket::bind(&"127.0.0.1:7777".parse()?)?;
let cloned = socket.try_clone();

socket.set_broadcast(false)?;
assert_eq!(socket.broadcast()?, cloned.broadcast()?);

Or something completely different?

[dtolnay]

Ideally the examples would show why someone would want to use the method. Your sample 1 and sample 2 are both examples of how to use the method, which is not as valuable as why someone would want to use the method. Users looking at mio documentation can be expected to understand the syntax of how to invoke a method, so showing them how to invoke try_clone is not helpful.

I would start by looking at crates that use mio, which of these methods they call as part of their realistic operation, and then use that to produce a short usage example that illustrates why the crate needs to call the method.

[lanedraex]

@dtolnay Agreed!

If you would be so kind as to answer another question.

Should some examples repeat steps like: binding a socket, registering a Poll; or should they be more focused on the method itself, and I just put some comments stating that a Poll was created before? Like so:

// Like this line:
// Create a Poll and register the socket

// Now we are ready to use it
socket.whatever()
.....

[dtolnay]

Great question. I would include as much surrounding steps as needed to make it clear why the example is doing what it is doing. If the repeated steps are just noise, it is okay to stub them out with a comment. If the repeated steps clarify where in the lifecycle of an application the important steps are taking place, in relation to where the Poll is created etc, then that is important context for the example.

[lanedraex]

Hey @dtolnay I wonder if you could tell me if I am going in the right direction with the examples, or if I'm missing the point (or am I somewhere in between?).

Don't know how to present it in a better way, but here are the examples I'm working on.

Fork link if you wish to build the docs locally.

[dtolnay]

Yes it looks like you are going in the right direction. Feel free to make several small PRs as you work, we don't need all 100 examples in a single PR.

I would focus on selecting examples that illustrate some detail of real-life usage of mio. So there can be simplifications and the occasional panic to keep things brief, but in terms of logic and control flow it should behave like something that a user of mio would want to write. I was thinking about this in the context of your local_addr example. Would someone intentionally try to bind, then if it fails compare the addresses? Or would they check another_socket.local_addr()? == dangerous_addr before trying to bind? Or is there a better way to solve this use case of binding to one socket or to a fallback?

[carllerche]

Closing due to inactivity.