Note that formatters should not return spurious errors.

Doing otherwise would break traits like `ToString`.

1 files changed, 8 insertions, 2 deletions

diff --git a/src/libcollections/fmt.rs b/src/libcollections/fmt.rs
index 428ed319ce9..a1b4461949c 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: