Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Provide a cleaner documentation for 'write!' #35279

Merged
merged 3 commits into from
Aug 12, 2016
Merged

Provide a cleaner documentation for 'write!' #35279

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
15be66d
Provide a cleaner documentation for 'write!'
cengizio Aug 4, 2016
800aa92
Use consistent spelling for word 'implementor'
cengizio Aug 4, 2016
c630bea
Be more explicit about duck typing
cengizio Aug 4, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 31 additions & 6 deletions src/libcore/macros.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,14 +229,26 @@ macro_rules! try {
})
}

/// Use the `format!` syntax to write data into a buffer.
/// Calls `write_fmt` function on a writer
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@steveklabnik Hello. Can you suggest a better, "friendlier" description instead of this? 😄

Copy link
Member

@nagisa nagisa Aug 4, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One question, should it be "Writes" or "Write"?

Some macros "Ensure", some "Asserts". I'm confused

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either works, I guess. I’m ambivalent, but @steveklabnik might have a stronger preference towards one of them.

///
/// This macro is typically used with a buffer of `&mut `[`Write`][write].
/// This macro takes an implementor of [`std::fmt::Write`][fmt_write] or
/// [`std::io::Write`][io_write] trait, a format string, and a list of arguments.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Implementation of macro does not seem to demand writer to implement any of these traits, only to have a method called write_fmt.

I feel like something along the lines of

This macro accepts any value with write_fmt method as a writer, a format string, and a list of arguments to format. write_fmt method usually comes from an implementation of [std::fmt::Write] or [std::io::Write] traits.

would be more technically correct.

///
/// Implementors of the `Write` trait are sometimes called 'writers'.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure which is correct, but on line 237 we have "Implementors" (with an O) and on line 234 "implementer" (with an E).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I decided to use "Implementor"

///
/// These arguments will be formatted according to the specified format string and
/// the resulting string will be passed to the writer.
///
/// Return value is either [`Result`][enum_result] or [`io::Result`][type_result] depending on
Copy link
Member

@nagisa nagisa Aug 4, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similarly to above, the return value is anything write_fmt method returns. It is nice to have return types of common sources of such method mentioned, though.

/// the writer.
///
/// See [`std::fmt`][fmt] for more information on format syntax.
///
/// [fmt]: ../std/fmt/index.html
/// [write]: ../std/io/trait.Write.html
/// [fmt_write]: ../std/fmt/trait.Write.html
/// [io_write]: ../std/io/trait.Write.html
/// [enum_result]: ../std/result/enum.Result.html
/// [type_result]: ../std/io/type.Result.html
///
/// # Examples
///
Expand All @@ -255,16 +267,29 @@ macro_rules! write {
($dst:expr, $($arg:tt)*) => ($dst.write_fmt(format_args!($($arg)*)))
}

/// Use the `format!` syntax to write data into a buffer, appending a newline.
/// Calls `write_fmt` function on a writer, with appending a newline.
///
/// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`)
/// alone (no additional CARRIAGE RETURN (`\r`/`U+000D`).
///
/// This macro is typically used with a buffer of `&mut `[`Write`][write].
/// This macro takes an implementor of [`std::fmt::Write`][fmt_write] or
/// [`std::io::Write`][io_write] trait, a format string, and a list of arguments.
///
/// Implementors of the `Write` trait are sometimes called 'writers'.
///
/// These arguments will be formatted according to the specified format string and
/// the resulting string will be passed to the writer.
///
/// Return value is either [`Result`][enum_result] or [`io::Result`][type_result] depending on
/// the writer.
///
/// See [`std::fmt`][fmt] for more information on format syntax.
///
/// [fmt]: ../std/fmt/index.html
/// [write]: ../std/io/trait.Write.html
/// [fmt_write]: ../std/fmt/trait.Write.html
/// [io_write]: ../std/io/trait.Write.html
/// [enum_result]: ../std/result/enum.Result.html
/// [type_result]: ../std/io/type.Result.html
///
/// # Examples
///
Expand Down