Rollup merge of #81465 - joshtriplett:duration-formatting-documentation, r=m-ou-se

Add documentation about formatting `Duration` values

Explain why Duration has a Debug impl but not a Display impl, and
mention the use of Unicode.

1 files changed, 11 insertions, 0 deletions

diff --git a/library/core/src/time.rs b/library/core/src/time.rs
index b1443bc33d2..8c0848c64aa 100644
--- a/library/core/src/time.rs
+++ b/library/core/src/time.rs
@@ -48,6 +48,17 @@ const MICROS_PER_SEC: u64 = 1_000_000;
 ///
 /// let ten_millis = Duration::from_millis(10);
 /// ```
+///
+/// # Formatting `Duration` values
+///
+/// `Duration` intentionally does not have a `Display` impl, as there are a
+/// variety of ways to format spans of time for human readability. `Duration`
+/// provides a `Debug` impl that shows the full precision of the value.
+///
+/// The `Debug` output uses the non-ASCII "µs" suffix for microseconds. If your
+/// program output may appear in contexts that cannot rely on full Unicode
+/// compatibility, you may wish to format `Duration` objects yourself or use a
+/// crate to do so.
 #[stable(feature = "duration", since = "1.3.0")]
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
 pub struct Duration {