diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs
index e6c3f549ec8e6..b73166ebef3d4 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
 ///