Add some more description of interactions between `Display` and `FromStr`

1 files changed, 6 insertions, 0 deletions

diff --git a/library/core/src/str/traits.rs b/library/core/src/str/traits.rs
index 85d5fa1ef92..2f425c82dc8 100644
--- a/library/core/src/str/traits.rs
+++ b/library/core/src/str/traits.rs
@@ -765,6 +765,12 @@ unsafe impl SliceIndex<str> for ops::RangeToInclusive<usize> {
 /// mistake, unless the type has provided and documented additional guarantees about its `Display`
 /// and `FromStr` implementations.
 ///
+/// If a type happens to have a lossless `Display` implementation whose output is meant to be
+/// conveniently machine-parseable and not just meant for human consumption, then the type may wish
+/// to accept the same format in `FromStr`, and document that usage. Having both `Display` and
+/// `FromStr` implementations where the result of `Display` cannot be parsed with `FromStr` may
+/// surprise users. (However, the result of such parsing may not have the same value as the input.)
+///
 /// # Examples
 ///
 /// Basic implementation of `FromStr` on an example `Point` type: