From 15be66dc04ee36af3ac29905b9172bd8227e4604 Mon Sep 17 00:00:00 2001 From: Cengiz Can Date: Thu, 4 Aug 2016 03:11:50 +0300 Subject: [PATCH 1/3] Provide a cleaner documentation for 'write!' --- src/libcore/macros.rs | 37 +++++++++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index b0c79a3a885..1846ca83e05 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -229,14 +229,26 @@ macro_rules! try { }) } -/// Use the `format!` syntax to write data into a buffer. +/// Calls `write_fmt` function on a writer /// -/// This macro is typically used with a buffer of `&mut `[`Write`][write]. +/// This macro takes an implementer of [`std::fmt::Write`][fmt_write] or +/// [`std::io::Write`][io_write] trait, a precompiled 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 /// @@ -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 implementer of [`std::fmt::Write`][fmt_write] or +/// [`std::io::Write`][io_write] trait, a precompiled 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 /// From 800aa92aa3da58b82e682947024c7868650e05bc Mon Sep 17 00:00:00 2001 From: Cengiz Can Date: Thu, 4 Aug 2016 03:55:37 +0300 Subject: [PATCH 2/3] Use consistent spelling for word 'implementor' --- src/libcore/macros.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index 1846ca83e05..961e91d3e2c 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -231,8 +231,8 @@ macro_rules! try { /// Calls `write_fmt` function on a writer /// -/// This macro takes an implementer of [`std::fmt::Write`][fmt_write] or -/// [`std::io::Write`][io_write] trait, a precompiled format string, and a list of arguments. +/// 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'. /// @@ -272,8 +272,8 @@ macro_rules! write { /// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) /// alone (no additional CARRIAGE RETURN (`\r`/`U+000D`). /// -/// This macro takes an implementer of [`std::fmt::Write`][fmt_write] or -/// [`std::io::Write`][io_write] trait, a precompiled format string, and a list of arguments. +/// 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'. /// From c630beaed7ed822bd576337d9e4afa20e781b994 Mon Sep 17 00:00:00 2001 From: Cengiz Can Date: Thu, 4 Aug 2016 04:33:50 +0300 Subject: [PATCH 3/3] Be more explicit about duck typing --- src/libcore/macros.rs | 44 +++++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index 961e91d3e2c..c916ad930ff 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -229,21 +229,23 @@ macro_rules! try { }) } -/// Calls `write_fmt` function on a writer +/// Write formatted data into a buffer /// -/// 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. +/// This macro accepts any value with `write_fmt` method as a writer, a format string, and a list +/// of arguments to format. /// -/// Implementors of the `Write` trait are sometimes called 'writers'. +/// `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'. /// -/// 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. +/// 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. +/// +/// Common return values are: [`Result`][enum_result], [`io::Result`][type_result] +/// /// [fmt]: ../std/fmt/index.html /// [fmt_write]: ../std/fmt/trait.Write.html /// [io_write]: ../std/io/trait.Write.html @@ -267,24 +269,26 @@ macro_rules! write { ($dst:expr, $($arg:tt)*) => ($dst.write_fmt(format_args!($($arg)*))) } -/// Calls `write_fmt` function on a writer, with appending a newline. +/// Write formatted data into a buffer, 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`). +/// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone +/// (no additional CARRIAGE RETURN (`\r`/`U+000D`). /// -/// 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. +/// This macro accepts any value with `write_fmt` method as a writer, a format string, and a list +/// of arguments to format. /// -/// Implementors of the `Write` trait are sometimes called 'writers'. +/// `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'. /// -/// 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. +/// 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. +/// +/// Common return values are: [`Result`][enum_result], [`io::Result`][type_result] +/// /// [fmt]: ../std/fmt/index.html /// [fmt_write]: ../std/fmt/trait.Write.html /// [io_write]: ../std/io/trait.Write.html