diff options
Diffstat (limited to 'vendor/thiserror/README.md')
| -rw-r--r-- | vendor/thiserror/README.md | 30 |
1 files changed, 26 insertions, 4 deletions
diff --git a/vendor/thiserror/README.md b/vendor/thiserror/README.md index 387a56e46..8f6b896de 100644 --- a/vendor/thiserror/README.md +++ b/vendor/thiserror/README.md @@ -124,8 +124,8 @@ pub enum DataStoreError { } ``` -- The Error trait's `backtrace()` method is implemented to return whichever - field has a type named `Backtrace`, if any. +- The Error trait's `provide()` method is implemented to provide whichever field + has a type named `Backtrace`, if any, as a `std::backtrace::Backtrace`. ```rust use std::backtrace::Backtrace; @@ -138,8 +138,9 @@ pub enum DataStoreError { ``` - If a field is both a source (named `source`, or has `#[source]` or `#[from]` - attribute) *and* is marked `#[backtrace]`, then the Error trait's - `backtrace()` method is forwarded to the source's backtrace. + attribute) *and* is marked `#[backtrace]`, then the Error trait's `provide()` + method is forwarded to the source's `provide` so that both layers of the error + share the same backtrace. ```rust #[derive(Error, Debug)] @@ -165,6 +166,27 @@ pub enum DataStoreError { } ``` + Another use case is hiding implementation details of an error representation + behind an opaque error type, so that the representation is able to evolve + without breaking the crate's public API. + + ```rust + // PublicError is public, but opaque and easy to keep compatible. + #[derive(Error, Debug)] + #[error(transparent)] + pub struct PublicError(#[from] ErrorRepr); + + impl PublicError { + // Accessors for anything we do want to expose publicly. + } + + // Private and free to change across minor version of the crate. + #[derive(Error, Debug)] + enum ErrorRepr { + ... + } + ``` + - See also the [`anyhow`] library for a convenient single error type to use in application code. |