Skip to content

Commit

Permalink
Update documentation of #[from] and #[backtrace] attributes
Browse files Browse the repository at this point in the history
  • Loading branch information
dtolnay committed Jul 17, 2024
1 parent 0bf6e3d commit de8a1e5
Show file tree
Hide file tree
Showing 2 changed files with 70 additions and 24 deletions.
38 changes: 27 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,20 +88,18 @@ pub enum DataStoreError {
}
```

- A `From` impl is generated for each variant containing a `#[from]` attribute.
- A `From` impl is generated for each variant that contains a `#[from]`
attribute.

Note that the variant must not contain any other fields beyond the source
error and possibly a backtrace. A backtrace is captured from within the `From`
impl if there is a field for it.
The variant using `#[from]` must not contain any other fields beyond the
source error (and possibly a backtrace — see below). Usually `#[from]`
fields are unnamed, but `#[from]` is allowed on a named field too.

```rust
#[derive(Error, Debug)]
pub enum MyError {
Io {
#[from]
source: io::Error,
backtrace: Backtrace,
},
Io(#[from] io::Error),
Glob(#[from] globset::Error),
}
```

Expand All @@ -125,7 +123,9 @@ pub enum DataStoreError {
```

- The Error trait's `provide()` method is implemented to provide whichever field
has a type named `Backtrace`, if any, as a `std::backtrace::Backtrace`.
has a type named `Backtrace`, if any, as a `std::backtrace::Backtrace`. Using
`Backtrace` in errors requires a nightly compiler with Rust version 1.73 or
newer.

```rust
use std::backtrace::Backtrace;
Expand All @@ -140,7 +140,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 `provide()`
method is forwarded to the source's `provide` so that both layers of the error
share the same backtrace.
share the same backtrace. The `#[backtrace]` attribute requires a nightly
compiler with Rust version 1.73 or newer.


```rust
#[derive(Error, Debug)]
Expand All @@ -152,6 +154,20 @@ pub enum DataStoreError {
}
```

- For variants that use `#[from]` and also contain a `Backtrace` field, a
backtrace is captured from within the `From` impl.

```rust
#[derive(Error, Debug)]
pub enum MyError {
Io {
#[from]
source: io::Error,
backtrace: Backtrace,
},
}
```

- Errors may use `error(transparent)` to forward the source and Display methods
straight through to an underlying error without adding an additional message.
This would be appropriate for enums that need an "anything else" variant.
Expand Down
56 changes: 43 additions & 13 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -98,24 +98,36 @@
//! }
//! ```
//!
//! - A `From` impl is generated for each variant containing a `#[from]`
//! - A `From` impl is generated for each variant that contains a `#[from]`
//! attribute.
//!
//! Note that the variant must not contain any other fields beyond the source
//! error and possibly a backtrace. A backtrace is captured from within the
//! `From` impl if there is a field for it.
//! The variant using `#[from]` must not contain any other fields beyond the
//! source error (and possibly a backtrace — see below). Usually
//! `#[from]` fields are unnamed, but `#[from]` is allowed on a named field
//! too.
//!
//! ```rust
//! # const IGNORE: &str = stringify! {
//! # use core::fmt::{self, Display};
//! # use std::io;
//! # use thiserror::Error;
//! #
//! # mod globset {
//! # #[derive(thiserror::Error, Debug)]
//! # #[error("...")]
//! # pub struct Error;
//! # }
//! #
//! #[derive(Error, Debug)]
//! pub enum MyError {
//! Io {
//! #[from]
//! source: io::Error,
//! backtrace: Backtrace,
//! },
//! Io(#[from] io::Error),
//! Glob(#[from] globset::Error),
//! }
//! # };
//! #
//! # impl Display for MyError {
//! # fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
//! # unimplemented!()
//! # }
//! # }
//! ```
//!
//! - The Error trait's `source()` method is implemented to return whichever
Expand Down Expand Up @@ -148,7 +160,8 @@
//!
//! - The Error trait's `provide()` method is implemented to provide whichever
//! field has a type named `Backtrace`, if any, as a
//! `std::backtrace::Backtrace`.
//! `std::backtrace::Backtrace`. Using `Backtrace` in errors requires a
//! nightly compiler with Rust version 1.73 or newer.
//!
//! ```rust
//! # const IGNORE: &str = stringify! {
Expand All @@ -165,7 +178,8 @@
//! - If a field is both a source (named `source`, or has `#[source]` or
//! `#[from]` 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.
//! both layers of the error share the same backtrace. The `#[backtrace]`
//! attribute requires a nightly compiler with Rust version 1.73 or newer.
//!
//! ```rust
//! # const IGNORE: &str = stringify! {
Expand All @@ -179,6 +193,22 @@
//! # };
//! ```
//!
//! - For variants that use `#[from]` and also contain a `Backtrace` field, a
//! backtrace is captured from within the `From` impl.
//!
//! ```rust
//! # const IGNORE: &str = stringify! {
//! #[derive(Error, Debug)]
//! pub enum MyError {
//! Io {
//! #[from]
//! source: io::Error,
//! backtrace: Backtrace,
//! },
//! }
//! # };
//! ```
//!
//! - Errors may use `error(transparent)` to forward the source and Display
//! methods straight through to an underlying error without adding an
//! additional message. This would be appropriate for enums that need an
Expand Down

0 comments on commit de8a1e5

Please sign in to comment.