Expand std::path::Display's docs

Part of #29368.
* Added explanation for why the struct exists
* Added link to where it is created
* Added example

1 files changed, 20 insertions, 1 deletions

diff --git a/src/libstd/path.rs b/src/libstd/path.rs
index 9c8eeb0c521..ce13b57f0a2 100644
--- a/src/libstd/path.rs
+++ b/src/libstd/path.rs
@@ -2236,7 +2236,26 @@ impl fmt::Debug for Path {
     }
 }
 
-/// Helper struct for safely printing paths with `format!()` and `{}`
+/// Helper struct for safely printing paths with [`format!`] and `{}`.
+///
+/// A [`Path`] might contain non-Unicode data. This `struct` implements the
+/// [`Display`] trait in a way that mitigates that. It is created by the
+/// [`display`][`Path::display`] method on [`Path`].
+///
+/// # Examples
+///
+/// ```
+/// use std::path::Path;
+///
+/// let path = Path::new("/tmp/foo.rs");
+///
+/// println!("{}", path.display());
+/// ```
+///
+/// [`Display`]: ../../std/fmt/trait.Display.html
+/// [`format!`]: ../../std/macro.format.html
+/// [`Path`]: struct.Path.html
+/// [`Path::display`]: struct.Path.html#method.display
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Display<'a> {
     path: &'a Path,