From 5547d927467ef3398c3f509f0212ba26645a18da Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Fri, 2 Apr 2021 15:11:49 +0300 Subject: [PATCH] Document "standard" conventions for error messages These are currently documented in the API guidelines: https://rust-lang.github.io/api-guidelines/interoperability.html#error-types-are-meaningful-and-well-behaved-c-good-err I think it makes sense to uplift this guideline (in a milder form) into std docs. Printing and producing errors is something that even non-expert users do frequently, so it is useful to give at least some indication of what a typical error message looks like. --- library/std/src/error.rs | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/library/std/src/error.rs b/library/std/src/error.rs index 80c35307d52ac..14c2f961d3261 100644 --- a/library/std/src/error.rs +++ b/library/std/src/error.rs @@ -33,15 +33,22 @@ use crate::string; use crate::sync::Arc; /// `Error` is a trait representing the basic expectations for error values, -/// i.e., values of type `E` in [`Result`]. Errors must describe -/// themselves through the [`Display`] and [`Debug`] traits, and may provide -/// cause chain information: +/// i.e., values of type `E` in [`Result`]. /// -/// [`Error::source()`] is generally used when errors cross -/// "abstraction boundaries". If one module must report an error that is caused -/// by an error from a lower-level module, it can allow accessing that error -/// via [`Error::source()`]. This makes it possible for the high-level -/// module to provide its own errors while also revealing some of the +/// Errors must describe themselves through the [`Display`] and [`Debug`] +/// traits. Error messages are typically concise lowercase sentences without +/// trailing punctuation: +/// +/// ``` +/// let err = "NaN".parse::().unwrap_err(); +/// assert_eq!(err.to_string(), "invalid digit found in string"); +/// ``` +/// +/// Errors may provide cause chain information. [`Error::source()`] is generally +/// used when errors cross "abstraction boundaries". If one module must report +/// an error that is caused by an error from a lower-level module, it can allow +/// accessing that error via [`Error::source()`]. This makes it possible for the +/// high-level module to provide its own errors while also revealing some of the /// implementation for debugging via `source` chains. #[stable(feature = "rust1", since = "1.0.0")] pub trait Error: Debug + Display {