Provide a cleaner documentation for 'write!' #35279
Conversation
|
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @brson (or someone else) soon. If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes. Please see the contribution instructions for more information. |
| /// This macro takes an implementer of [`std::fmt::Write`][fmt_write] or | ||
| /// [`std::io::Write`][io_write] trait, a precompiled format string, and a list of arguments. | ||
| /// | ||
| /// Implementors of the `Write` trait are sometimes called 'writers'. |
There was a problem hiding this comment.
Not sure which is correct, but on line 237 we have "Implementors" (with an O) and on line 234 "implementer" (with an E).
There was a problem hiding this comment.
Hmm. Thanks for noticing.
I'm not sure though. This says they're just different spellings. https://en.wiktionary.org/wiki/implementer#English
And I grepped both of them right now
user@host:~/Source/rust/src(master⚡) » ack "mplementor" -c -h
89
user@host:~/Source/rust/src(master⚡) » ack "mplementer" -c -h
13
There was a problem hiding this comment.
I decided to use "Implementor"
|
Thanks @cengizio. This is definitely an improvement. The new description 'Calls cc @nagisa |
| @@ -231,8 +231,8 @@ macro_rules! try { | |||
|
|
|||
| /// Calls `write_fmt` function on a writer | |||
There was a problem hiding this comment.
@steveklabnik Hello. Can you suggest a better, "friendlier" description instead of this? 😄
|
@brson Thank you! You're right. I wasn't happy with the new description I came up either. We should come up with a better one. I wanted to warn the developer about duck typing and two different return types with two different writers. |
| @@ -229,14 +229,26 @@ macro_rules! try { | |||
| }) | |||
| } | |||
|
|
|||
| /// Use the `format!` syntax to write data into a buffer. | |||
| /// Calls `write_fmt` function on a writer | |||
There was a problem hiding this comment.
Perhaps
Write formatted data into a buffer
could be a better first sentence? Note that this sentence is a short summary that user will see in rustdoc search and various listings, so it is not necessary to provide implementation details here.
There was a problem hiding this comment.
That looks much better. Thank you.
I was already aware that it needed to be as short as possible, since I compiled the docs and experienced it.
There was a problem hiding this comment.
One question, should it be "Writes" or "Write"?
Some macros "Ensure", some "Asserts". I'm confused
There was a problem hiding this comment.
Either works, I guess. I’m ambivalent, but @steveklabnik might have a stronger preference towards one of them.
|
Thanks for taking this! It certainly looks better than before. |
|
LGTM 👍 |
|
📌 Commit c630bea has been approved by |
|
Thanks everybody! I think this will be merged later. Am I right? |
|
@cengizio yup! all r+'d commits go into a queue: https://buildbot.rust-lang.org/homu/queue/rust @bors then tests them and does the merge. You shoudn't need to do anything unless for some reason, @bors finds a problem. |
Provide a cleaner documentation for 'write!' Hello! This is my attempt to fix rust-lang#35110 Any feedback is more than welcome! Cheers!
Provide a cleaner documentation for 'write!' Hello! This is my attempt to fix rust-lang#35110 Any feedback is more than welcome! Cheers!
Provide a cleaner documentation for 'write!' Hello! This is my attempt to fix rust-lang#35110 Any feedback is more than welcome! Cheers!
Hello!
This is my attempt to fix #35110
Any feedback is more than welcome!
Cheers!