rustdoc: extend UdpSocket API doc (#657) #44378
Conversation
|
r? @aturon (rust_highfive has picked a reviewer for you, use r? to override) |
|
@dtolnay please review |
src/libstd/net/udp.rs
Outdated
| @@ -48,12 +48,12 @@ use time::Duration; | |||
| /// { | |||
| /// let mut socket = UdpSocket::bind("127.0.0.1:34254")?; | |||
| /// | |||
| /// // read from the socket | |||
| /// // read from the socket a single message, `buf` must be of sufficient size to hold the message | |||
There was a problem hiding this comment.
// Read a single message from the socket.
// If `buf` is too small to hold the message, it will be cut off.
src/libstd/net/udp.rs
Outdated
| /// 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]; | ||
| /// let buf = &mut buf[..amt]; // slice as bounded view onto `buf` |
There was a problem hiding this comment.
// create a slice into the buffer that's no longer than the received data
aidanhs
added
the
S-waiting-on-review
src/libstd/net/udp.rs
Outdated
| @@ -48,12 +48,14 @@ use time::Duration; | |||
| /// { | |||
| /// let mut socket = UdpSocket::bind("127.0.0.1:34254")?; | |||
| /// | |||
| /// // read from the socket | |||
| /// // Read a single message from the socket. If `buf` is too small to hold | |||
| /// // the message, it will be cut off. | |||
There was a problem hiding this comment.
// 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.
src/libstd/net/udp.rs
Outdated
| /// of bytes read and the address from whence the data came. | ||
| /// The function must be called with valid byte array `buf` of sufficient size to | ||
| /// hold the message bytes. If a message is too long to fit in the supplied buffer, | ||
| /// excess bytes may be discarded. |
There was a problem hiding this comment.
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.
|
Text has been modified, hope it fits now |
|
There was a problem hiding this comment.
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
| /// Receives data on the socket from the remote address to which it is | ||
| /// connected. | ||
| /// Receives a single datagram message on the socket from the remote address to | ||
| /// which it is connected. On success, returns the number of bytes read. |
There was a problem hiding this comment.
one more iteration ;)
|
|
I don't think #44378 (review) has been addressed yet. |
|
finally. Thanks for your patience |
|
No problem! Thanks for keeping with it! @bors: r+ rollup |
|
📌 Commit 04b8747 has been approved by |
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):
@bors r- |
rustdoc: type-fixes
|
finally, finally |
|
Ready to merge? |
|
@bors r+ rollup |
|
📌 Commit 85a9d97 has been approved by |
rustdoc: extend UdpSocket API doc (rust-lang#657) see tokio-rs/mio#657
see tokio-rs/mio#657