nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-11-23 23:34:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document "standard" conventions for error messages

Browse Source 
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:
Aleksey Kladov 2021-04-02 15:11:49 +03:00
parent 5662d9343f
commit 5547d92746
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::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 {