Rollup merge of rust-lang#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 rust-lang#37472 ; posted separately to avoid mixing the new documentation with copyedits to existing documentation.)

Author: Jonathan Turner

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
 ///