rustdoc: extend UdpSocket API doc (#657)

[frehberg]

see tokio-rs/mio#657

[rust-highfive]

r? @aturon

(rust_highfive has picked a reviewer for you, use r? to override)

[frehberg]

@dtolnay please review

[mattico]

Some ideas about the wording

[mattico]

// Read a single message from the socket.
// If `buf` is too small to hold the message, it will be cut off.

[mattico]

// create a slice into the buffer that's no longer than the received data

[aidanhs]

Thanks for the PR @frehberg! We'll check in now and again to make sure @aturon or another reviewer gets to this soon.

[dtolnay]

Thanks! This is a nice improvement.

Both of my comments apply elsewhere in this PR as well.

[dtolnay]

// Read a single message from the socket. If `buf` is too small to hold
// the message, it will be cut off.
let mut buf = [0; 10];
let (amt, src) = socket.recv_from(&mut buf)?;

// send a reply to the socket we received data from
let buf = &mut buf[..amt]; // create a slice into the buffer that's
                           // no longer than the received data

This feels jarring to me in that it uses a mix of sentence-case and lowercase, punctuation and no punctuation, and full line and end of line comments. Could you tidy this up to make it feel more consistent? Typically I prefer sentence-case, with punctuation, and comments without any code on the same line. But check the rest of this module because if everything else is consistently in a different style, let's follow that.

[dtolnay]

Quoting from the documentation documentation:

The first line of a documentation comment should be a short summary of its functionality. One sentence. Just the basics. High level.

(I think by "line" they mean "paragraph" -- everything before the first blank line. The first paragraph is special in rustdoc. For example it is visible in the module-level documentation before you click through on the function.)

Everything you wrote is important to document but not all of it is high level basics. Could you split this into two paragraphs? The first one should give a general understanding of what the function does, and the second fills in the details.

[frehberg]

Text has been modified, hope it fits now

[steveklabnik]

[00:02:54] tidy error: /checkout/src/libstd/net/udp.rs:107: trailing whitespace

[00:02:54] tidy error: /checkout/src/libstd/net/udp.rs:139: trailing whitespace

[dtolnay]

Almost looks good to me but please rephrase all three other comments to be consistent with the one I indicated. There are a few inconsistencies.

Read a single message from the socket
Receives a single datagram message from socket
Receives a single datagram message on the socket
Receives single datagram on the socket

... on success returning number of bytes
On success returning number of bytes
On success, returns the number of bytes

[dtolnay]

This one is great.

[frehberg]

one more iteration ;)

[steveklabnik]

[00:03:28] tidy error: /checkout/src/libstd/net/udp.rs:107: trailing whitespace

[00:03:28] tidy error: /checkout/src/libstd/net/udp.rs:139: trailing whitespace

[dtolnay]

I don't think #44378 (review) has been addressed yet.

[frehberg]

finally. Thanks for your patience

[steveklabnik]

No problem! Thanks for keeping with it!

@bors: r+ rollup

[bors]

📌 Commit 04b8747 has been approved by steveklabnik

[dtolnay]

On success returning the number of bytes read.

I don't think this sentence is grammatically correct -- just like "Going fishing" is not a complete sentence. I would prefer to word this (and the other ones similarly) like the one I indicated in #44378 (review):

On success, returns the number of bytes read.

@bors r-

[frehberg]

finally, finally

[frehberg]

Ready to merge?

[dtolnay]

@bors r+ rollup

[dtolnay]

@bors r+ rollup

[bors]

📌 Commit 85a9d97 has been approved by dtolnay