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.

1 files changed, 15 insertions, 8 deletions

diff --git a/library/std/src/error.rs b/library/std/src/error.rs
index 80c35307d52..14c2f961d32 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<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 {