Rollup merge of #38946 - GuillaumeGomez:path_doc, r=frewsxcv

Add missing links and examples for path modules and structs

r? @frewsxcv

1 files changed, 95 insertions, 22 deletions

diff --git a/src/libstd/path.rs b/src/libstd/path.rs
index 3f9bf70adde..bf105a50d64 100644
--- a/src/libstd/path.rs
+++ b/src/libstd/path.rs
@@ -10,9 +10,9 @@
 
 //! Cross-platform path manipulation.
 //!
-//! This module provides two types, `PathBuf` and `Path` (akin to `String` and
-//! `str`), for working with paths abstractly. These types are thin wrappers
-//! around `OsString` and `OsStr` respectively, meaning that they work directly
+//! This module provides two types, [`PathBuf`] and [`Path`][`Path`] (akin to [`String`]
+//! and [`str`]), for working with paths abstractly. These types are thin wrappers
+//! around [`OsString`] and [`OsStr`] respectively, meaning that they work directly
 //! on strings according to the local platform's path syntax.
 //!
 //! ## Simple usage
@@ -20,10 +20,10 @@
 //! Path manipulation includes both parsing components from slices and building
 //! new owned paths.
 //!
-//! To parse a path, you can create a `Path` slice from a `str`
+//! To parse a path, you can create a [`Path`] slice from a [`str`]
 //! slice and start asking questions:
 //!
-//! ```rust
+//! ```
 //! use std::path::Path;
 //! use std::ffi::OsStr;
 //!
@@ -39,9 +39,9 @@
 //! assert_eq!(extension, Some(OsStr::new("txt")));
 //! ```
 //!
-//! To build or modify paths, use `PathBuf`:
+//! To build or modify paths, use [`PathBuf`]:
 //!
-//! ```rust
+//! ```
 //! use std::path::PathBuf;
 //!
 //! let mut path = PathBuf::from("c:\\");
@@ -103,6 +103,13 @@
 //! that `b` is a symbolic link (so its parent isn't `a`). Further
 //! normalization is possible to build on top of the components APIs,
 //! and will be included in this library in the near future.
+//!
+//! [`PathBuf`]: ../../std/path/struct.PathBuf.html
+//! [`Path`]: ../../std/path/struct.Path.html
+//! [`String`]: ../../std/string/struct.String.html
+//! [`str`]: ../../std/primitive.str.html
+//! [`OsString`]: ../../std/ffi/struct.OsString.html
+//! [`OsStr`]: ../../std/ffi/struct.OsStr.html
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
@@ -527,7 +534,9 @@ pub struct Components<'a> {
     back: State,
 }
 
-/// An iterator over the components of a path, as `OsStr` slices.
+/// An iterator over the components of a path, as [`OsStr`] slices.
+///
+/// [`OsStr`]: ../../std/ffi/struct.OsStr.html
 #[derive(Clone)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Iter<'a> {
@@ -1089,10 +1098,11 @@ impl PathBuf {
 
     /// Updates [`self.file_name()`] to `file_name`.
     ///
-    /// If [`self.file_name()`] was `None`, this is equivalent to pushing
+    /// If [`self.file_name()`] was [`None`], this is equivalent to pushing
     /// `file_name`.
     ///
     /// [`self.file_name()`]: struct.PathBuf.html#method.file_name
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     ///
     /// # Examples
     ///
@@ -1124,11 +1134,12 @@ impl PathBuf {
     ///
     /// If [`self.file_name()`] is `None`, does nothing and returns `false`.
     ///
-    /// Otherwise, returns `true`; if [`self.extension()`] is `None`, the
+    /// Otherwise, returns `true`; if [`self.extension()`] is [`None`], the
     /// extension is added; otherwise it is replaced.
     ///
     /// [`self.file_name()`]: struct.PathBuf.html#method.file_name
     /// [`self.extension()`]: struct.PathBuf.html#method.extension
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     ///
     /// # Examples
     ///
@@ -1356,8 +1367,10 @@ pub struct Path {
     inner: OsStr,
 }
 
-/// An error returned from the `Path::strip_prefix` method indicating that the
+/// An error returned from the [`Path::strip_prefix`] method indicating that the
 /// prefix was not found in `self`.
+///
+/// [`Path::strip_prefix`]: struct.Path.html#method.strip_prefix
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[stable(since = "1.7.0", feature = "strip_prefix")]
 pub struct StripPrefixError(());
@@ -1539,7 +1552,9 @@ impl Path {
 
     /// The path without its final component, if any.
     ///
-    /// Returns `None` if the path terminates in a root or prefix.
+    /// Returns [`None`] if the path terminates in a root or prefix.
+    ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     ///
     /// # Examples
     ///
@@ -1570,7 +1585,9 @@ impl Path {
 
     /// The final component of the path, if it is a normal file.
     ///
-    /// If the path terminates in `..`, `file_name` will return `None`.
+    /// If the path terminates in `..`, `file_name` will return [`None`].
+    ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
     ///
     /// # Examples
     ///
@@ -1608,8 +1625,11 @@ impl Path {
     ///
     /// # Errors
     ///
-    /// If `base` is not a prefix of `self` (i.e. `starts_with`
-    /// returns `false`), returns `Err`.
+    /// If `base` is not a prefix of `self` (i.e. [`starts_with`]
+    /// returns `false`), returns [`Err`].
+    ///
+    /// [`starts_with`]: #method.starts_with
+    /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
     ///
     /// # Examples
     ///
@@ -1689,11 +1709,13 @@ impl Path {
     ///
     /// The stem is:
     ///
-    /// * None, if there is no file name;
+    /// * [`None`], if there is no file name;
     /// * The entire file name if there is no embedded `.`;
     /// * The entire file name if the file name begins with `.` and has no other `.`s within;
     /// * Otherwise, the portion of the file name before the final `.`
     ///
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    ///
     /// # Examples
     ///
     /// ```
@@ -1710,15 +1732,16 @@ impl Path {
 
     /// Extracts the extension of [`self.file_name()`], if possible.
     ///
-    /// [`self.file_name()`]: struct.Path.html#method.file_name
-    ///
     /// The extension is:
     ///
-    /// * None, if there is no file name;
-    /// * None, if there is no embedded `.`;
-    /// * None, if the file name begins with `.` and has no other `.`s within;
+    /// * [`None`], if there is no file name;
+    /// * [`None`], if there is no embedded `.`;
+    /// * [`None`], if the file name begins with `.` and has no other `.`s within;
     /// * Otherwise, the portion of the file name after the final `.`
     ///
+    /// [`self.file_name()`]: struct.Path.html#method.file_name
+    /// [`None`]: ../../std/option/enum.Option.html#variant.None
+    ///
     /// # Examples
     ///
     /// ```
@@ -1877,7 +1900,6 @@ impl Path {
         Display { path: self }
     }
 
-
     /// Query the file system to get information about a file, directory, etc.
     ///
     /// This function will traverse symbolic links to query information about the
@@ -1886,6 +1908,16 @@ impl Path {
     /// This is an alias to [`fs::metadata`].
     ///
     /// [`fs::metadata`]: ../fs/fn.metadata.html
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use std::path::Path;
+    ///
+    /// let path = Path::new("/Minas/tirith");
+    /// let metadata = path.metadata().expect("metadata call failed");
+    /// println!("{:?}", metadata.file_type());
+    /// ```
     #[stable(feature = "path_ext", since = "1.5.0")]
     pub fn metadata(&self) -> io::Result<fs::Metadata> {
         fs::metadata(self)
@@ -1896,6 +1928,16 @@ impl Path {
     /// This is an alias to [`fs::symlink_metadata`].
     ///
     /// [`fs::symlink_metadata`]: ../fs/fn.symlink_metadata.html
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use std::path::Path;
+    ///
+    /// let path = Path::new("/Minas/tirith");
+    /// let metadata = path.symlink_metadata().expect("symlink_metadata call failed");
+    /// println!("{:?}", metadata.file_type());
+    /// ```
     #[stable(feature = "path_ext", since = "1.5.0")]
     pub fn symlink_metadata(&self) -> io::Result<fs::Metadata> {
         fs::symlink_metadata(self)
@@ -1907,6 +1949,15 @@ impl Path {
     /// This is an alias to [`fs::canonicalize`].
     ///
     /// [`fs::canonicalize`]: ../fs/fn.canonicalize.html
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use std::path::{Path, PathBuf};
+    ///
+    /// let path = Path::new("/foo/test/../test/bar.rs");
+    /// assert_eq!(path.canonicalize().unwrap(), PathBuf::from("/foo/test/bar.rs"));
+    /// ```
     #[stable(feature = "path_ext", since = "1.5.0")]
     pub fn canonicalize(&self) -> io::Result<PathBuf> {
         fs::canonicalize(self)
@@ -1917,6 +1968,15 @@ impl Path {
     /// This is an alias to [`fs::read_link`].
     ///
     /// [`fs::read_link`]: ../fs/fn.read_link.html
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use std::path::Path;
+    ///
+    /// let path = Path::new("/laputa/sky_castle.rs");
+    /// let path_link = path.read_link().expect("read_link call failed");
+    /// ```
     #[stable(feature = "path_ext", since = "1.5.0")]
     pub fn read_link(&self) -> io::Result<PathBuf> {
         fs::read_link(self)
@@ -1932,6 +1992,19 @@ impl Path {
     /// [`io::Result`]: ../io/type.Result.html
     /// [`DirEntry`]: ../fs/struct.DirEntry.html
     /// [`fs::read_dir`]: ../fs/fn.read_dir.html
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use std::path::Path;
+    ///
+    /// let path = Path::new("/laputa");
+    /// for entry in path.read_dir().expect("read_dir call failed") {
+    ///     if let Ok(entry) = entry {
+    ///         println!("{:?}", entry.path());
+    ///     }
+    /// }
+    /// ```
     #[stable(feature = "path_ext", since = "1.5.0")]
     pub fn read_dir(&self) -> io::Result<fs::ReadDir> {
         fs::read_dir(self)