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.

1 files changed, 20 insertions, 18 deletions

diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs
index e6c3f549ec8..b73166ebef3 100644
--- a/src/libcore/macros.rs
+++ b/src/libcore/macros.rs
@@ -316,26 +316,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
 ///
@@ -354,31 +355,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
 ///