RFC 2230: bury-description

libs (traits | error-handling)

• Feature Name: optional_error_description
• Start Date: 2017-11-29
• RFC PR: rust-lang/rfcs#2230
• Rust Issue: (leave this empty)

Default implementation of Error::description()

Provide a default implementation of the Error trait's description() method to save users trouble of implementing this flawed method.

Motivation

The description() method is a waste of time for implementors and users of the Error trait. There's high overlap between description and Display, which creates redundant implementation work and confusion about relationship of these two ways of displaying the error.

The description() method can't easily return a formatted string with per-instance error description. That's a gotcha for novice users struggling with the borrow checker, and gotcha for users trying to display the error, because the description() is going to return a less informative message than the Display trait.

Guide-level explanation

Let's steer users away from the description() method.

1. Change the description() documentation to suggest use of the Display trait instead.
2. Provide a default implementation of the description() so that the Error trait can be implemented without worrying about this method.

Reference-level explanation

Users of the Error trait can then pretend this method does not exist.

Drawbacks

When users start omitting bespoke description() implementations, code that still uses this method will start getting default strings instead of human-written description. If this becomes a problem, the description() method can also be formally deprecated (with the #[deprecated] attribute). However, there's no urgency to remove existing implementations of description(), so this RFC does not propose formal deprecation at this time to avoid unnecessary warnings during the transition.

Rationale and alternatives

• Do nothing, and rely on 3rd party crates to improve usability of errors (e.g. various crates providing Error-implementing macros or the Fail trait).
• The default message returned by description could be different.
  • it could be a hardcoded generic string, e.g. "error",
  • it could return core::intrinsics::type_name::<Self>(),
  • it could try to be nicer, e.g. use the type's doccomment as the description, or convert type name to a sentence (FileNotFoundError -> "error: file not found").

Unresolved questions

None yet.