From a7183a9978390604a1e9348a61d19230ab1347fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=B3=96=E9=9C=B2=E6=98=9F=E9=9C=9C=E2=80=A2=E6=9A=96?=
 =?UTF-8?q?=E9=9C=9E=E6=8B=BE=E5=85=89?= <2468001320@qq.com>
Date: Sun, 13 Sep 2026 16:43:31 +0000
Subject: [PATCH] docs: document that #[from] on an opaque type needs
 forwarding From impls for ? conversion

---
 README.md  | 13 +++++++++++++
 src/lib.rs | 30 ++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/README.md b/README.md
index 7c67cb2f..e4217cf0 100644
--- a/README.md
+++ b/README.md
@@ -201,6 +201,19 @@ pub enum DataStoreError {
   }
   ```
 
+  Note that `#[from]` on the outer opaque type only supplies `From<ErrorRepr>`.
+  The `?` operator performs a single conversion step, so code returning
+  `PublicError` that uses `?` on one of the underlying error types directly
+  needs its own forwarding implementation on `PublicError`:
+
+  ```rust
+  impl From<Foo> for PublicError {
+      fn from(err: Foo) -> Self {
+          Self(ErrorRepr::from(err))
+      }
+  }
+  ```
+
 - See also the [`anyhow`] library for a convenient single error type to use in
   application code.
 
diff --git a/src/lib.rs b/src/lib.rs
index 3980fabc..d11965fb 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -251,6 +251,36 @@
 //!   }
 //!   ```
 //!
+//!   Note that `#[from]` on the outer opaque type only supplies
+//!   `From<ErrorRepr>`. The `?` operator performs a single conversion
+//!   step, so code returning `PublicError` that uses `?` on one of the
+//!   underlying error types directly needs its own forwarding
+//!   implementation on `PublicError`:
+//!
+//!   ```
+//!   # use thiserror::Error;
+//!   #
+//!   # #[derive(Error, Debug)]
+//!   # #[error(transparent)]
+//!   # pub struct PublicError(#[from] ErrorRepr);
+//!   #
+//!   # #[derive(Error, Debug)]
+//!   # #[error("foo")]
+//!   # struct Foo;
+//!   #
+//!   # #[derive(Error, Debug)]
+//!   # enum ErrorRepr {
+//!   #     #[error("foo")]
+//!   #     Foo(#[from] Foo),
+//!   # }
+//!   #
+//!   impl From<Foo> for PublicError {
+//!       fn from(err: Foo) -> Self {
+//!           Self(ErrorRepr::from(err))
+//!       }
+//!   }
+//!   ```
+//!
 //! - See also the [`anyhow`] library for a convenient single error type to use
 //!   in application code.
 //!