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

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.
 

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.
 //!