Improve the documentation of `Display` and `FromStr`, and their interactions

In particular:
- `Display` is not necessarily lossless
- The output of `Display` might not be parseable by `FromStr`, and might
  not produce the same value if it is.
- Calling `.parse()` on the output of `Display` is usually a mistake
  unless a type's documented output and input formats match.
- The input formats accepted by `FromStr` depend on the type.

2 files changed, 18 insertions, 0 deletions

diff --git a/library/core/src/fmt/mod.rs b/library/core/src/fmt/mod.rs
index 5978cb660f6..c25ef9ba512 100644
--- a/library/core/src/fmt/mod.rs
+++ b/library/core/src/fmt/mod.rs
@@ -928,6 +928,15 @@ pub use macros::Debug;
 /// [tostring]: ../../std/string/trait.ToString.html
 /// [tostring_function]: ../../std/string/trait.ToString.html#tymethod.to_string
 ///
+/// # Completeness and parseability
+///
+/// `Display` for a type might not necessarily be a lossless or complete representation of the type.
+/// It may omit internal state, precision, or other information the type does not consider important
+/// for user-facing output, as determined by the type. As such, the output of `Display` might not be
+/// possible to parse, and even if it is, the result of parsing might not exactly match the original
+/// value. Calling `.parse()` on the output from `Display` is usually a mistake, unless the type has
+/// provided and documented additional guarantees about its `Display` and `FromStr` implementations.
+///
 /// # Internationalization
 ///
 /// Because a type can only have one `Display` implementation, it is often preferable
diff --git a/library/core/src/str/traits.rs b/library/core/src/str/traits.rs
index 4baf9aacad7..85d5fa1ef92 100644
--- a/library/core/src/str/traits.rs
+++ b/library/core/src/str/traits.rs
@@ -756,6 +756,15 @@ unsafe impl SliceIndex<str> for ops::RangeToInclusive<usize> {
 /// parse an `i32` with `FromStr`, but not a `&i32`. You can parse a struct that
 /// contains an `i32`, but not one that contains an `&i32`.
 ///
+/// # Input format
+///
+/// The input format expected by a type's `FromStr` implementation depends on the type. Check the
+/// type's documentation for the input formats it knows how to parse. Note that the input format of
+/// a type's `FromStr` implementation might not necessarily accept the output format of its
+/// `Display` implementation; thus, calling `.parse()` on the output from `Display` is usually a
+/// mistake, unless the type has provided and documented additional guarantees about its `Display`
+/// and `FromStr` implementations.
+///
 /// # Examples
 ///
 /// Basic implementation of `FromStr` on an example `Point` type: