`std::fmt::Write` methods error documentation

[yoav-lavi]

Location

std::fmt::Write

Summary

While opening this issue for Clippy, I noticed that many of the write_xyz methods have the following error description:

Errors

This function will return an instance of Error on error.

While I understand that this is due to the description being general for any implementation, this can seem tautological to someone that's not familiar with these methods and I thought perhaps it'd make sense to expand this a bit and add common scenarios / scenarios implemented by the standard library.

write_fmt seems to be missing this description in general.

Thank you!

[vincenzopalazzo]

@rustbot label +T-docs-rs +E-easy

[fprasx]

Hi, I've been looking into this and I can't find an actual implementation of the Write trait. All I can find is implementations for types that contain a dyn Write already. Seems kinda like a chicken and egg problem, I can only find impl's when the trait has already been implemented. I looked at mod.rs for core::fmt, and all the impl's were chicken-eggy. Does anybody who knows more about this know where I could look to find an actual implementation? If you point me in the right place, I'd be hapy to submit a pull improving the docs :)

[Havvy]

The implementors section shows that String and Formatter<'_> implement the trait. Neither implementation returns the error directly though.

[thedanvail]

Would it be fair to have the docs say something along the lines of:

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 advisable to check the implementation of this trait and program around any possible [`Error`]s.

That way, it is clear that std doesn't produce any errors and also that the user should be aware that it is a possibility in third-party crates.

[kpreid]

std doesn't produce any errors

It does: 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.