tcp: add usage examples to TcpListener and TcpStream #775
Conversation
Adding doc tests and usage examples to the public methods of `TcpListener` and `TcpStream`. The documented methods are: - tokio-tcp/src/listener.rs#bind - tokio-tcp/src/listener.rs#accept - tokio-tcp/src/listener.rs#poll_accept - tokio-tcp/src/listener.rs#accept_std - tokio-tcp/src/listener.rs#poll_accept_std - tokio-tcp/src/listener.rs#from_std - tokio-tcp/src/listener.rs#local_addr - tokio-tcp/src/listener.rs#incoming - tokio-tcp/src/listener.rs#ttl - tokio-tcp/src/listener.rs#set_ttl - tokio-tcp/src/stream.rs#connect - tokio-tcp/src/stream.rs#from_std - tokio-tcp/src/stream.rs#poll_read_ready - tokio-tcp/src/stream.rs#poll_write_ready - tokio-tcp/src/stream.rs#local_addr - tokio-tcp/src/stream.rs#peer_addr - tokio-tcp/src/stream.rs#peek - tokio-tcp/src/stream.rs#poll_peek - tokio-tcp/src/stream.rs#shutdown - tokio-tcp/src/stream.rs#nodelay - tokio-tcp/src/stream.rs#set_nodelay - tokio-tcp/src/stream.rs#recv_buffer_size - tokio-tcp/src/stream.rs#set_recv_buffer_size - tokio-tcp/src/stream.rs#send_buffer_size - tokio-tcp/src/stream.rs#set_send_buffer_size - tokio-tcp/src/stream.rs#keepalive - tokio-tcp/src/stream.rs#set_keepalive - tokio-tcp/src/stream.rs#ttl - tokio-tcp/src/stream.rs#set_ttl - tokio-tcp/src/stream.rs#linger - tokio-tcp/src/stream.rs#set_linger - tokio-tcp/src/stream.rs#try_clone Refs: rustasync/team#54
|
This is my first pass at documenting the Struct methods. Looking forward to your feedback. |
|
@mattgathu One question, because my knowledge of doctests is minimal: it looks like some of the lines have leading # and some don't.. i.e. all of the Why is that? |
|
@tobz the |
|
Ahhh, TIL! |
There was a problem hiding this comment.
I actually went back and did a better review... and it actually looks like some of the examples comment out all of the use statements. Is that... correct? Obviously it will still compile but I had taken the lack of the leading # on some of them to be a show of what needed to be used for types that were being shown in the code... and some of these examples theoretically won't show any use statements at all, despite utilizing some of these types.
tokio-tcp/src/stream.rs
Outdated
| /// # use futures::Async; | ||
| /// # use futures::Future; | ||
| /// # use tokio_tcp::TcpStream; | ||
| /// # use std::net::SocketAddr; |
There was a problem hiding this comment.
Looks like there's some inconsistency here where we aren't showing any of the use statements at all?
There was a problem hiding this comment.
So I wasn't sure exactly what to show and what to hide. Do you have a preference or rule of thumb I could follow?
There was a problem hiding this comment.
Another thing to consider is that the TcpListener and TcpStream are mostly not used in isolation, which makes it a bit hard to provide meaningful examples.
For instance, the tinyhttp.rs in Examples has this snippet:
let addr = env::args().nth(1).unwrap_or("127.0.0.1:8080".to_string());
let addr = addr.parse::<SocketAddr>()?;
let listener = TcpListener::bind(&addr)?;
println!("Listening on: {}", addr);
tokio::run({
listener.incoming()
.map_err(|e| println!("failed to accept socket; error = {:?}", e))
.for_each(|socket| {
process(socket);
Ok(())
})
});This actually shows how to use the TcpListener with the Tokio runtime and could be really useful to have in the documentation but this is hard - the doctests will fail since the runtime is not part of the tcp crate.
There was a problem hiding this comment.
@mattgathu You can include the tokio runtime in the doc tests. Add a dev-dependency to tokio in the tokio-tcp crate 👍
There was a problem hiding this comment.
LGTM Thanks so much for doing this ❤️
Re @tobz thoughts, up until now, we haven't really had a good rule of thumb about what to include. However, it probably is best to include more than less, including extern crate and use statements.
That said, we can open an issue to discuss the conventions and address it later across the all the examples in the repo.
|
@mattgathu I'm happy to merge this whenever. I commented above that you can depend on the Tokio runtime in the doc examples for each crate. If you want to do that, go for it. Let me know when you want this merged 👍 |
|
@carllerche awesome. let me update the docs and include |
* update the doc tests/usage examples to use tokio::net. * made all `use` statements visible * simplified some examples (use consistent wording) * added `no_run` to tests that may cause block or cause port contention
|
@tobz @carllerche I have updated the docs:
you might give it a quick glance before merging: 42052c2 |
|
Yep, looks good to me! :) |
|
And, it goes without saying: thank you for your contribution! |
|
❤️ ❤️ ❤️ 🌮 |
Motivation
Request by the Networking Working Group to help document tokio.
rustasync/team#54
Solution
Adding doc tests and usage examples to the public methods
of
TcpListenerandTcpStream. The documented methods are:Refs: rustasync/team#54