Rollup merge of #136687 - joshtriplett:improve-display-and-fromstr-docs, r=Amanieu

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.

This documentation adds no API surface area and makes no guarantees about stability. To the best of my knowledge, everything it says is already established to be true. As such, I don't think it needs an FCP.

2 files changed, 28 insertions, 0 deletions

diff --git a/library/core/src/fmt/mod.rs b/library/core/src/fmt/mod.rs
index 5978cb660f6..145e581d1fb 100644
--- a/library/core/src/fmt/mod.rs
+++ b/library/core/src/fmt/mod.rs
@@ -928,6 +928,20 @@ 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.
+///
+/// However, if a type has 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.
+///
 /// # 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..b9559c83171 100644
--- a/library/core/src/str/traits.rs
+++ b/library/core/src/str/traits.rs
@@ -756,6 +756,20 @@ 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 and round-tripping
+///
+/// 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, and even if it does, the `Display` implementation may not be lossless
+/// so the round-trip may lose information.
+///
+/// However, if a type has 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.
+///
 /// # Examples
 ///
 /// Basic implementation of `FromStr` on an example `Point` type: