mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #83780 - matklad:doc-error-message, r=JohnTitor

Browse Source 
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.
This commit is contained in:
Yuki Okushi 2021-04-04 00:19:37 +09:00 committed by GitHub
commit 961fa632d6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 15 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
library/std/src/error.rs
View File

@ -33,15 +33,22 @@
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 {