Rollup merge of #35862 - Stebalien:fmt-docs, r=steveklabnik

Clarify/fix formatting docs concerning fmt::Result/fmt::Error

1. `fmt::Result` != `io::Result<()>`
2. Formatters should only propagate errors, not return their own.

Confusion on reddit: https://www.reddit.com/r/rust/comments/4yorxr/is_implt_tostring_for_t_where_t_display_sized_a/

1 files changed, 9 insertions, 3 deletions

diff --git a/src/libcollections/fmt.rs b/src/libcollections/fmt.rs
index b7cbfb60ec4..beb3e6b3d4e 100644
--- a/src/libcollections/fmt.rs
+++ b/src/libcollections/fmt.rs
@@ -165,9 +165,15 @@
 //! 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).
+//! 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: