Update provider API docs

library/core/src/error.rs

@@ -205,6 +205,52 @@ pub trait Error: Debug + Display {
     ///     assert!(request_ref::<MyLittleTeaPot>(dyn_error).is_none());
     /// }
     /// ```
+    ///
+    /// # Implementation Conventions
+    ///
+    /// <div class="warning">
+    ///
+    /// **We recommend implementors avoid delegating implementations of `provide` to source error
+    /// implementations.**
+    ///
+    /// This method should expose context from the current piece of the source chain only, not from
+    /// sources. Delegating `provide` implementations cause the same context to be provided by
+    /// multiple errors in the chain of sources which can cause unintended duplication of
+    /// information in error reports or require heuristics to deduplicate.
+    ///
+    /// In otherwords, the following implementation pattern for `provide` is discouraged and should
+    /// not be used for Error types exposed in public APIs to third parties.
+    ///
+    /// </div>
+    ///
+    /// ```rust
+    /// # #![feature(error_generic_member_access)]
+    /// # use core::fmt;
+    /// # use core::error::{request_ref, Request};
+    /// # #[derive(Debug)]
+    /// struct MyError {
+    ///     source: Error,
+    /// }
+    /// # #[derive(Debug)]
+    /// # struct Error;
+    /// # impl fmt::Display for Error {
+    /// #     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    /// #         write!(f, "Example Source Error")
+    /// #     }
+    /// # }
+    /// # impl fmt::Display for MyError {
+    /// #     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+    /// #         write!(f, "Example Error")
+    /// #     }
+    /// # }
+    /// # impl std::error::Error for Error { }
+    ///
+    /// impl std::error::Error for MyError {
+    ///     fn provide<'a>(&'a self, request: &mut Request<'a>) {
+    ///         self.source.provide(request)
+    ///     }
+    /// }
+    /// ```
     #[unstable(feature = "error_generic_member_access", issue = "99301")]
     #[allow(unused_variables)]
     fn provide<'a>(&'a self, request: &mut Request<'a>) {}