From e4dd785b591b771882b1c61a541048d57dc86442 Mon Sep 17 00:00:00 2001 From: Steven Allen Date: Sat, 20 Aug 2016 15:20:22 -0400 Subject: [PATCH 1/3] Correct formatting docs: fmt::Result != io::Result<()> --- src/libcollections/fmt.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/libcollections/fmt.rs b/src/libcollections/fmt.rs index b7cbfb60ec4e9..428ed319ce941 100644 --- a/src/libcollections/fmt.rs +++ b/src/libcollections/fmt.rs @@ -165,9 +165,9 @@ //! provides some helper methods. //! //! Additionally, the return value of this function is `fmt::Result` which is a -//! typedef to `Result<(), std::io::Error>` (also known as `std::io::Result<()>`). -//! Formatting implementations should ensure that they return errors from `write!` -//! correctly (propagating errors upward). +//! typedef to `Result<(), std::fmt::Error>`. Formatting implementations should +//! ensure that they return errors from `write!` correctly (propagating errors +//! upward). //! //! An example of implementing the formatting traits would look //! like: From f2655e23ff1b377f09cfbb19253a7ea50cd2c4f3 Mon Sep 17 00:00:00 2001 From: Steven Allen Date: Sat, 20 Aug 2016 15:27:37 -0400 Subject: [PATCH 2/3] Note that formatters should not return spurious errors. Doing otherwise would break traits like `ToString`. --- src/libcollections/fmt.rs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/libcollections/fmt.rs b/src/libcollections/fmt.rs index 428ed319ce941..a1b4461949c6e 100644 --- a/src/libcollections/fmt.rs +++ b/src/libcollections/fmt.rs @@ -166,8 +166,14 @@ //! //! Additionally, the return value of this function is `fmt::Result` which is a //! typedef to `Result<(), std::fmt::Error>`. Formatting implementations should -//! ensure that they return errors from `write!` correctly (propagating errors -//! upward). +//! ensure that they propagate errors from the `Formatter` (e.g., when calling +//! `write!`) however, they should never return errors spuriously. That is, a +//! formatting implementation must and may only return an error if the passed-in +//! `Formatter` returns an error. This is because, contrary to what the function +//! signature might suggest, string formatting is an infallible operation. +//! This function only returns a result because writing to the underlying stream +//! might fail and it must provide a way to propagate the fact that an error has +//! occurred back up the stack. //! //! An example of implementing the formatting traits would look //! like: From c7d5f7e5e638775e45c4fdc64f3b91bdbfca9c28 Mon Sep 17 00:00:00 2001 From: Steven Allen Date: Tue, 23 Aug 2016 10:47:28 -0400 Subject: [PATCH 3/3] Rust has type aliases, not typedefs. They're the same thing but it's better to keep the terminology consistent. --- src/libcollections/fmt.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/libcollections/fmt.rs b/src/libcollections/fmt.rs index a1b4461949c6e..beb3e6b3d4e31 100644 --- a/src/libcollections/fmt.rs +++ b/src/libcollections/fmt.rs @@ -165,15 +165,15 @@ //! provides some helper methods. //! //! Additionally, the return value of this function is `fmt::Result` which is a -//! typedef to `Result<(), std::fmt::Error>`. Formatting implementations should -//! ensure that they propagate errors from the `Formatter` (e.g., when calling -//! `write!`) however, they should never return errors spuriously. That is, a -//! formatting implementation must and may only return an error if the passed-in -//! `Formatter` returns an error. This is because, contrary to what the function -//! signature might suggest, string formatting is an infallible operation. -//! This function only returns a result because writing to the underlying stream -//! might fail and it must provide a way to propagate the fact that an error has -//! occurred back up the stack. +//! type alias of `Result<(), std::fmt::Error>`. Formatting implementations +//! should ensure that they propagate errors from the `Formatter` (e.g., when +//! calling `write!`) however, they should never return errors spuriously. That +//! is, a formatting implementation must and may only return an error if the +//! passed-in `Formatter` returns an error. This is because, contrary to what +//! the function signature might suggest, string formatting is an infallible +//! operation. This function only returns a result because writing to the +//! underlying stream might fail and it must provide a way to propagate the fact +//! that an error has occurred back up the stack. //! //! An example of implementing the formatting traits would look //! like: