Skip to content

docs: clarify backtrace capture behavior in README - #457

Open
eastspire wants to merge 1 commit into
dtolnay:masterfrom
eastspire:fix/readme-backtrace-wording
Open

docs: clarify backtrace capture behavior in README#457
eastspire wants to merge 1 commit into
dtolnay:masterfrom
eastspire:fix/readme-backtrace-wording

Conversation

@eastspire

@eastspire eastspire commented Aug 17, 2026

Copy link
Copy Markdown

Closes #409

Summary

The README and the corresponding crate-level rustdoc currently state that
a backtrace is captured and printed with the error "if the underlying
error type does not already provide its own". This wording implies that
anyhow always checks the underlying error, but in fact that check is
only performed on nightly Rust when the unstable
error_generic_member_access feature is enabled (see
src/backtrace.rs). On stable, anyhow unconditionally captures a
backtrace.

This rewording:

  • Describes the stable behavior first ("a backtrace is captured and
    printed with the error"), removing the misleading conditional.
  • Explicitly calls out the nightly-only opt-out: on nightly with
    error_generic_member_access, anyhow additionally detects when the
    underlying error type already provides a backtrace and avoids
    capturing a second one.

Changes

File Lines
README.md 78-83
src/lib.rs 131-136

Both files contain essentially the same paragraph (the rustdoc is
mirrored from the README), so they are updated together to keep them
in sync.

Test plan

  • cargo build
  • cargo test (including 26 doc-tests, which exercise the
    updated rustdoc paragraph)
  • cargo fmt --all -- --check
  • cargo clippy --all-targets -- -D warnings

The previous wording stated that a backtrace is captured and printed with
the error "if the underlying error type does not already provide its own",
implying that anyhow always checks the underlying error. In fact, that
check is only performed on nightly Rust when the unstable
`error_generic_member_access` feature is enabled (see src/backtrace.rs).
On stable, anyhow unconditionally captures a backtrace.

Reword the README and the corresponding crate-level rustdoc to describe
the stable behavior first, and explicitly call out the nightly-only
opt-out for errors that already provide a backtrace.

Closes dtolnay#409
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Readme claims backtraces captured "if the underlying error type does not already provide its own"

1 participant