Guidance for what to write in Error::description()

[dtolnay]

My understanding is that nothing should ever use description(). Most errors will have a significantly more helpful Display representation than what the signature of description() allows.

Nevertheless, description() is there and has to return something.

[Enet4]

My understanding is that nothing should ever use description()

That's quite a claim. Can you provide some examples of what would be a good practice here? I would actually imagine certain implementations of Display relying on description().

[dtolnay]

Sure we can make exceptions for the person implementing Error in the following limited circumstances:

• You can call description to implement Display of the same error type.
• You can call description to implement description of a different error type.

But the point is that a user of the library should never have an error value and decide to call description on it instead of using Display.

Guidelines for where description vs Display should be called are not in scope for the API guidelines project because they do not affect the API of a library. It is in scope for Clippy so I filed https://github.com/Manishearth/rust-clippy/issues/1780 to follow up over there.

[Kixunil]

I personally find description and Display redundant. I (almost?) always end up implementing Display via description()

[dtolnay]

@Kixunil you're missing out! Display can usually be much more informative than description.

[Kixunil]

@dtolnay I actually do it like this: write!(f, "{}: {}", self.description(), self.additional_info) to avoid copy-pasting same thing.

[dtolnay]

Okay great. That is what #71 (comment) means by "You can call description to implement Display of the same error type."

[Kixunil]

Yes, I understand. What I want to say is that description() is probably unneeded. (But we have to support it since it's stable now.)

[dtolnay]

I agree.

[dtolnay]

Added a note about description() in 0c5f968.