From cc8259e4b6b1c8c390969ad24ce09ca502b55f69 Mon Sep 17 00:00:00 2001 From: Dan Vail Date: Sun, 7 Aug 2022 21:02:04 -0500 Subject: [PATCH 1/2] Adding more verbose documentation for `std::fmt::Write` --- library/core/src/fmt/mod.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/library/core/src/fmt/mod.rs b/library/core/src/fmt/mod.rs index 372141e0933f5..80f37cb5fdba5 100644 --- a/library/core/src/fmt/mod.rs +++ b/library/core/src/fmt/mod.rs @@ -119,6 +119,13 @@ pub trait Write { /// /// This function will return an instance of [`Error`] on error. /// + /// Though it is possible for implementors of this trait to return an error, at the time + /// of writing these docs, no implementation of [`std::fmt::Write`] in the standard library + /// returns such an error. + /// + /// When working with external crates, it is advised to check the implementation of this + /// trait and anticipate any possible [`Error`]s. + /// /// # Examples /// /// ``` From ee8a01f596d7d5aeeb817565492e5534e3bd4737 Mon Sep 17 00:00:00 2001 From: Dan Vail Date: Tue, 9 Aug 2022 12:57:19 -0500 Subject: [PATCH 2/2] Switching documentation to be more clear about potential errors --- library/core/src/fmt/mod.rs | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/library/core/src/fmt/mod.rs b/library/core/src/fmt/mod.rs index 80f37cb5fdba5..7ec565edb3483 100644 --- a/library/core/src/fmt/mod.rs +++ b/library/core/src/fmt/mod.rs @@ -119,12 +119,9 @@ pub trait Write { /// /// This function will return an instance of [`Error`] on error. /// - /// Though it is possible for implementors of this trait to return an error, at the time - /// of writing these docs, no implementation of [`std::fmt::Write`] in the standard library - /// returns such an error. - /// - /// When working with external crates, it is advised to check the implementation of this - /// trait and anticipate any possible [`Error`]s. + /// The purpose of std::fmt::Error is to abort the formatting operation when the underlying + /// destination encounters some error preventing it from accepting more text; it should + /// generally be propagated rather than handled, at least when implementing formatting traits. /// /// # Examples ///