Document that Display entails ToString and should be lossless and infallible

[JKAnderson409]

#92941
Taking what was said here and in the issue itself, I tried to be concise and explicit. I kept my lines to 80 characters according to the guide.

I want to be able to write docs like the ones in std so any feedback is appreciated. This is also my first contribution so I apologize if I made mistakes in the submission process.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @m-ou-se (or someone else) soon.

Please see the contribution instructions for more information.

[the8472]

I don't think this is universally true. In the Path case it's because it is very tempting to treat paths as strings so not doing a lossy to_string avoids people running into that footgun.

But for complex aggregate types which don't implement FromStr or similar one doesn't necessarily expect the display to be a lossless representation of its internal state.

[JKAnderson409]

From the thread:

A weak heuristic: If you're not going to bother making a `FromStr` too, just skip `Display` .
...
`Debug` and `serde` support are the important ones, most of the time.

This implies that the String returned by to_string should losslessly represent the state of the instance. I guess this is exactly what the issue is trying to clear up.

[the8472]

That kind of seems backwards to me. If it is user-facing (as the documentation says) then there should be no assumption about FromStr which is more of a serialization or user-input thing. Not everything that can be shown to a user must be parsable.
So where does that heuristic come from?

Again, for simple types representing just one thing I kind of can see it. But for complex types I would apply different heuristics.

I guess we can discuss this somewhere else, I just want to register my general disagreement.

[JKAnderson409]

I agree that it's a bit confusing. For me, it clears things up to think of this as applying only with the context of the standard library's formatter. The std::fmt module is defined as, "Utilities for formatting and printing Strings." When we do things like print!("{}", thing) we rely on Display but you could define a Print or Show trait that applies to a different use case.

[joshtriplett]

Suggested change

	/// `Display` is similar to [`Debug`], but `Display` is for user-facing output,
	/// and so cannot be derived. When `Display` is implemented, the [`ToString`]
	/// `Display` is similar to [`Debug`], but `Display` is for user-facing output.
	/// When `Display` is implemented, the [`ToString`]

As long as we're fixing this documentation: this conclusion doesn't actually automatically follow, and might not always be true.

[joshtriplett]

But for complex aggregate types which don't implement FromStr or similar one doesn't necessarily expect the display to be a lossless representation of its internal state.

Agreed; in particular, the "lossless" phrasing might encourage people to produce Display impls that don't do as good a job at being human-readable, because they over-focus on round-tripping.

[JohnCSimon]

Ping from triage:
@JKAnderson409 Can you please post your status on this PR? Thanks.

FYI: when a PR is ready for review, send a message containing
@rustbot ready to switch to S-waiting-on-review so the PR is in the reviewer's backlog.

[JKAnderson409]

@rustbot ready

Sorry I've been out for a long time but I'm back in the office today.

FYI, the Book gives the impression that Display can be lossy and that it cannot be derived. If this change means that it may become derivable, then that suggested change by @joshtriplett should go in.

An example of a trait that can’t be derived is Display, which handles formatting for end users. You should always consider the appropriate way to display a type to an end user. What parts of the type should an end user be allowed to see? What parts would they find relevant? What format of the data would be most relevant to them? The Rust compiler doesn’t have this insight, so it can’t provide appropriate default behavior for you.

[RaduBerinde]

How do you define lossless here? Any definition I can think of feels way too strict..

[GuillaumeGomez]

"doesn't lose information from its internal data" and then we can use Path as an example?

[GuillaumeGomez]

Suggested change

	/// directly (but offers a .display() method).
	/// directly (but offers a `.display()` method).

[bors]

☔ The latest upstream changes (presumably #102331) made this pull request unmergeable. Please resolve the merge conflicts.

[KittyBorgX]

@rustbot author
@JKAnderson409 Hey! It looks like there are some merge conflicts, can you sort them out?
Also, any update on the status of the PR? There are pending review changes that some reviewers have suggested so it'd be great if you can sort all of these out.

Once you're done doing everything, type in @rustbot review here to change the tag to S-waiting-on-review

[Dylan-DPC]

Closing this pr due to inactivity. If you wish you can reöpen this PR or create a new one when you have the time for it and we can take it forward from there