Clarify Display for error should not include source

1 files changed, 7 insertions, 1 deletions

diff --git a/library/core/src/error.rs b/library/core/src/error.rs
index 92b3c83d1bf..9ca91ee009e 100644
--- a/library/core/src/error.rs
+++ b/library/core/src/error.rs
@@ -16,13 +16,19 @@ use crate::fmt::{self, Debug, Display, Formatter};
 /// assert_eq!(err.to_string(), "invalid digit found in string");
 /// ```
 ///
+/// # Error source
+///
 /// Errors may provide cause information. [`Error::source()`] is generally
 /// used when errors cross "abstraction boundaries". If one module must report
 /// an error that is caused by an error from a lower-level module, it can allow
-/// accessing that error via [`Error::source()`]. This makes it possible for the
+/// accessing that error via `Error::source()`. This makes it possible for the
 /// high-level module to provide its own errors while also revealing some of the
 /// implementation for debugging.
 ///
+/// In error types that wrap an underlying error, the underlying error
+/// should be either returned by the outer error's `Error::source()`, or rendered
+/// by the outer error's `Display` implementation, but not both.
+///
 /// # Example
 ///
 /// Implementing the `Error` trait only requires that `Debug` and `Display` are implemented too.