Document "standard" conventions for error messages

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<T, E>`]. Errors must describe
-/// themselves through the [`Display`] and [`Debug`] traits, and may provide
-/// cause chain information:
+/// i.e., values of type `E` in [`Result<T, E>`].
 ///
-/// [`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::<u32>().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 {