Rollup merge of #37473 - joshtriplett:doc-copyedit-write-writeln, r=alexcrichton

Copyediting on documentation for write! and writeln!

Fix various sentence fragments, missing articles, and other grammatical issues in the documentation for write! and writeln!.

Also fix the links (and link names) for common return types.

(Noticed when preparing https://github.com/rust-lang/rust/pull/37472 ; posted separately to avoid mixing the new documentation with copyedits to existing documentation.)

1 files changed, 20 insertions, 18 deletions

diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs
index f69a60d9e1f..cae46a0dd0f 100644
--- a/src/libcore/macros.rs
+++ b/src/libcore/macros.rs
@@ -317,26 +317,27 @@ macro_rules! try {
 
 /// Write formatted data into a buffer
 ///
-/// This macro accepts any value with `write_fmt` method as a writer, a format string, and a list
-/// of arguments to format.
+/// This macro accepts a 'writer' (any value with a `write_fmt` method), a format string, and a
+/// list of arguments to format.
 ///
-/// `write_fmt` method usually comes from an implementation of [`std::fmt::Write`][fmt_write] or
-/// [`std::io::Write`][io_write] traits. These are sometimes called 'writers'.
+/// The `write_fmt` method usually comes from an implementation of [`std::fmt::Write`][fmt_write]
+/// or [`std::io::Write`][io_write] traits. The term 'writer' refers to an implementation of one of
+/// these two traits.
 ///
 /// Passed arguments will be formatted according to the specified format string and the resulting
 /// string will be passed to the writer.
 ///
 /// See [`std::fmt`][fmt] for more information on format syntax.
 ///
-/// Return value is completely dependent on the 'write_fmt' method.
+/// `write!` returns whatever the 'write_fmt' method returns.
 ///
-/// Common return values are: [`Result`][enum_result], [`io::Result`][type_result]
+/// Common return values include: [`fmt::Result`][fmt_result], [`io::Result`][io_result]
 ///
 /// [fmt]: ../std/fmt/index.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
+/// [fmt_result]: ../std/fmt/type.Result.html
+/// [io_result]: ../std/io/type.Result.html
 ///
 /// # Examples
 ///
@@ -355,31 +356,32 @@ macro_rules! write {
     ($dst:expr, $($arg:tt)*) => ($dst.write_fmt(format_args!($($arg)*)))
 }
 
-/// Write formatted data into a buffer, with appending a newline.
+/// Write formatted data into a buffer, with a newline appended.
 ///
 /// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone
 /// (no additional CARRIAGE RETURN (`\r`/`U+000D`).
 ///
-/// This macro accepts any value with `write_fmt` method as a writer, a format string, and a list
-/// of arguments to format.
+/// This macro accepts a 'writer' (any value with a `write_fmt` method), a format string, and a
+/// list of arguments to format.
 ///
-/// `write_fmt` method usually comes from an implementation of [`std::fmt::Write`][fmt_write] or
-/// [`std::io::Write`][io_write] traits. These are sometimes called 'writers'.
+/// The `write_fmt` method usually comes from an implementation of [`std::fmt::Write`][fmt_write]
+/// or [`std::io::Write`][io_write] traits. The term 'writer' refers to an implementation of one of
+/// these two traits.
 ///
 /// Passed arguments will be formatted according to the specified format string and the resulting
-/// string will be passed to the writer.
+/// string will be passed to the writer, along with the appended newline.
 ///
 /// See [`std::fmt`][fmt] for more information on format syntax.
 ///
-/// Return value is completely dependent on the 'write_fmt' method.
+/// `write!` returns whatever the 'write_fmt' method returns.
 ///
-/// Common return values are: [`Result`][enum_result], [`io::Result`][type_result]
+/// Common return values include: [`fmt::Result`][fmt_result], [`io::Result`][io_result]
 ///
 /// [fmt]: ../std/fmt/index.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
+/// [fmt_result]: ../std/fmt/type.Result.html
+/// [io_result]: ../std/io/type.Result.html
 ///
 /// # Examples
 ///