Skip to content

docs: document that #[from] on an opaque type needs forwarding From impls for ? conversion - #456

Open
TrueFurina wants to merge 1 commit into
dtolnay:masterfrom
TrueFurina:docs/from-opaque-forwarding
Open

TrueFurina wants to merge 1 commit into
dtolnay:masterfrom
TrueFurina:docs/from-opaque-forwarding

Conversation

@TrueFurina

Copy link
Copy Markdown

Fixes #439.

Problem

The "hiding implementation details behind an opaque error type" example in both the crate docs and the README shows pub struct PublicError(#[from] ErrorRepr) with an elided ErrorRepr body. Users who fill in the body exactly as suggested by the issue (variants like Foo(#[from] Foo)) then write throw_foo()? in a function returning Result<(), PublicError> and get:

error[E0277]: `?` couldn't convert the error to `PublicError`
  = help: the trait `From<Foo>` is not implemented for `PublicError`
          but trait `From<ErrorRepr>` is implemented for it

This is not a derive bug: #[from] on the outer opaque type supplies From<ErrorRepr> only, and ? performs a single conversion step. But the docs actively teach a shape that hits this trap with no warning.

Fix (docs-only)

  • Both the crate-level docs (src/lib.rs) and README.md now note that #[from] on the opaque type only supplies From<ErrorRepr>, and that ?-based direct conversion from an underlying error type needs its own forwarding impl.
  • src/lib.rs adds a compilable doctest showing the forwarding impl (impl From<Foo> for PublicError); README.md shows the same snippet.
  • No runtime or macro behavior is changed. If maintainers would rather solve this at the derive level (e.g. transitively generating From for #[from] leaf types), I'm happy to close this in favor of that direction — [Feature request] Enabling support for transitive "#[from]' handling #435/#[from] without implying #[source] #422 discuss related #[from] semantics.

Testing

  • cargo test --doc — 11 passed / 0 failed (10 pre-existing + the new forwarding-impl doctest)
  • Repro from the issue verified failing on thiserror 2.0.20 before the doc change (E0277), and the documented forwarding impl resolves it

@TrueFurina

Copy link
Copy Markdown
Author

Friendly ping - this is still open on my side and mergeable as far as I can tell. Happy to address any remaining feedback if something is blocking it. Thanks!

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.

example from documentation does not compile

1 participant