From 4dbd2562b4e2c464218a2949442becad34d55955 Mon Sep 17 00:00:00 2001 From: Christopher Durham Date: Tue, 13 Feb 2024 22:24:29 -0500 Subject: [PATCH 1/2] Explain use of display adapters --- library/core/src/fmt/mod.rs | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/library/core/src/fmt/mod.rs b/library/core/src/fmt/mod.rs index e1b7b46a1ed..f82e8a0d60b 100644 --- a/library/core/src/fmt/mod.rs +++ b/library/core/src/fmt/mod.rs @@ -633,6 +633,23 @@ pub(crate) mod macros { /// [tostring]: ../../std/string/trait.ToString.html /// [tostring_function]: ../../std/string/trait.ToString.html#tymethod.to_string /// +/// # Internationalization +/// +/// Because a type only has one `Display` implementation, it is often preferable +/// to only implement `Display` when there is a single most "obvious" way that +/// values can be formatted as text. This could mean formatting according to the +/// "invariant" culture and "undefined" locale, or it could mean that the type +/// display is designed for a specific culture/locale, such as developer logs. +/// +/// If not all values have a justifiably canonical textual format or if you want +/// to support alternative formats not covered by the standard set of possible +/// [formatting traits], the most flexible approach is display adapters: methods +/// like [`str::escape_default`] or [`Path::display`] which create a wrapper +/// implementing `Display` to output the specific display format. +/// +/// [formatting traits]: ../../std/fmt/index.html#formatting-traits +/// [`Path::display`]: ../../std/path/struct.Path.html#method.display +/// /// # Examples /// /// Implementing `Display` on a type: From 215a4b6c2d71f2f7dd6254fcecbfc15bbc6fb392 Mon Sep 17 00:00:00 2001 From: Christopher Durham Date: Mon, 4 Mar 2024 19:49:45 -0500 Subject: [PATCH 2/2] doc wording improvements Co-authored-by: Simon Farnsworth --- library/core/src/fmt/mod.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/fmt/mod.rs b/library/core/src/fmt/mod.rs index f82e8a0d60b..4d73c8c3f99 100644 --- a/library/core/src/fmt/mod.rs +++ b/library/core/src/fmt/mod.rs @@ -635,7 +635,7 @@ pub(crate) mod macros { /// /// # Internationalization /// -/// Because a type only has one `Display` implementation, it is often preferable +/// Because a type can only have one `Display` implementation, it is often preferable /// to only implement `Display` when there is a single most "obvious" way that /// values can be formatted as text. This could mean formatting according to the /// "invariant" culture and "undefined" locale, or it could mean that the type