Skip to content

Adding more verbose documentation for std::fmt::Write #100255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bors merged 3 commits into from
Aug 12, 2022
Merged

Adding more verbose documentation for std::fmt::Write #100255

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cc8259e
Adding more verbose documentation for `std::fmt::Write`
thedanvail Aug 8, 2022
0436067
Merge branch 'rust-lang:master' into issue-98861-fix
thedanvail Aug 9, 2022
ee8a01f
Switching documentation to be more clear about potential errors
thedanvail Aug 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions library/core/src/fmt/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

@kpreid kpreid Aug 9, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This claim is false. The internal implementation of std::fmt::Write for an Adapter that wraps a std::io::Write produces a fmt::Error when the underlying destination returns a std::io::Error (while saving that error internally and returning it after the formatting is cancelled).

This can be observed in user code by implementing a formatting trait which is then used with io::Write::write_fmt() on a destination that errors.

I think better advice to give here is something like “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.”

Copy link
Contributor Author

@thedanvail thedanvail Aug 9, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, I missed that! Thanks for the heads up. I'll make the change with your suggestion, run the checks, and push the commit.

///
/// When working with external crates, it is advised to check the implementation of this
/// trait and anticipate any possible [`Error`]s.
///
/// # Examples
///
/// ```
Expand Down