From 714bc477bde2520fcfa79ad9938667795f30b260 Mon Sep 17 00:00:00 2001 From: Jeff Date: Tue, 1 Mar 2022 10:37:19 -0500 Subject: [PATCH] Document that Display entails ToString and should be lossless and infallible --- library/core/src/fmt/mod.rs | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/library/core/src/fmt/mod.rs b/library/core/src/fmt/mod.rs index 90c5719f486cb..834bee04a3d91 100644 --- a/library/core/src/fmt/mod.rs +++ b/library/core/src/fmt/mod.rs @@ -697,11 +697,21 @@ pub use macros::Debug; /// Format trait for an empty format, `{}`. /// -/// `Display` is similar to [`Debug`], but `Display` is for user-facing -/// output, and so cannot be derived. +/// `Display` is similar to [`Debug`], but `Display` is for user-facing output, +/// and so cannot be derived. When `Display` is implemented, the [`ToString`] +/// trait is implemented automatically, adding the `to_string` method to all +/// `Display` types. +/// +/// A `Display` implementation should be lossless and infallible, otherwise it +/// does not fit the API. For example, converting a path to a [`String`] is +/// potentially lossy or fallible, so [`Path`] doesn’t implement `Display` +/// directly (but offers a .display() method). /// /// For more information on formatters, see [the module-level documentation][module]. /// +/// [`Path`]: ../../std/path/struct.Path.html +/// [`ToString`]: ../../std/string/trait.ToString.html +/// [`String`]: ../../std/string/struct.String.html /// [module]: ../../std/fmt/index.html /// /// # Examples