From 1a886bc3c93a40090cda155fe2bfdcc8bd8e0e69 Mon Sep 17 00:00:00 2001 From: Simonas Kazlauskas Date: Wed, 3 Feb 2016 01:16:58 +0200 Subject: [PATCH] Improve docs for Path::methods --- src/libstd/path.rs | 80 +++++++++++++++++++++++++++++----------------- 1 file changed, 51 insertions(+), 29 deletions(-) diff --git a/src/libstd/path.rs b/src/libstd/path.rs index 207c4d02e4817..10ecaed3aefd6 100644 --- a/src/libstd/path.rs +++ b/src/libstd/path.rs @@ -1823,76 +1823,98 @@ impl Path { } - /// Gets information on the file, directory, etc at this path. + /// Query the file system to get information about a file, directory, etc. /// - /// Consult the `fs::metadata` documentation for more info. + /// This function will traverse symbolic links to query information about the + /// destination file. /// - /// This call preserves identical runtime/error semantics with - /// `fs::metadata`. + /// This is an alias to `fs::metadata`. #[stable(feature = "path_ext", since = "1.5.0")] pub fn metadata(&self) -> io::Result { fs::metadata(self) } - /// Gets information on the file, directory, etc at this path. + /// Query the metadata about a file without following symlinks. /// - /// Consult the `fs::symlink_metadata` documentation for more info. - /// - /// This call preserves identical runtime/error semantics with - /// `fs::symlink_metadata`. + /// This is an alias to `fs::symlink_metadata`. #[stable(feature = "path_ext", since = "1.5.0")] pub fn symlink_metadata(&self) -> io::Result { fs::symlink_metadata(self) } - /// Returns the canonical form of a path, normalizing all components and - /// eliminate all symlinks. + /// Returns the canonical form of the path with all intermediate components + /// normalized and symbolic links resolved. /// - /// This call preserves identical runtime/error semantics with - /// `fs::canonicalize`. + /// This is an alias to `fs::canonicalize`. #[stable(feature = "path_ext", since = "1.5.0")] pub fn canonicalize(&self) -> io::Result { fs::canonicalize(self) } - /// Reads the symlink at this path. + /// Reads a symbolic link, returning the file that the link points to. /// - /// For more information see `fs::read_link`. + /// This is an alias to `fs::read_link`. #[stable(feature = "path_ext", since = "1.5.0")] pub fn read_link(&self) -> io::Result { fs::read_link(self) } - /// Reads the directory at this path. + /// Returns an iterator over the entries within a directory. + /// + /// The iterator will yield instances of `io::Result`. New errors may + /// be encountered after an iterator is initially constructed. /// - /// For more information see `fs::read_dir`. + /// This is an alias to `fs::read_dir`. #[stable(feature = "path_ext", since = "1.5.0")] pub fn read_dir(&self) -> io::Result { fs::read_dir(self) } - /// Boolean value indicator whether the underlying file exists on the local - /// filesystem. Returns false in exactly the cases where `fs::metadata` - /// fails. + /// Returns whether the path points at an existing entity. + /// + /// This function will traverse symbolic links to query information about the + /// destination file. In case of broken symbolic links this will return `false`. + /// + /// # Examples + /// + /// ```no_run + /// use std::path::Path; + /// assert_eq!(Path::new("does_not_exist.txt").exists(), false); + /// ``` #[stable(feature = "path_ext", since = "1.5.0")] pub fn exists(&self) -> bool { fs::metadata(self).is_ok() } - /// Whether the underlying implementation (be it a file path, or something - /// else) points at a "regular file" on the FS. Will return false for paths - /// to non-existent locations or directories or other non-regular files - /// (named pipes, etc). Follows links when making this determination. + /// Returns whether the path is pointing at a regular file. + /// + /// This function will traverse symbolic links to query information about the + /// destination file. In case of broken symbolic links this will return `false`. + /// + /// # Examples + /// + /// ```no_run + /// use std::path::Path; + /// assert_eq!(Path::new("./is_a_directory/").is_file(), false); + /// assert_eq!(Path::new("a_file.txt").is_file(), true); + /// ``` #[stable(feature = "path_ext", since = "1.5.0")] pub fn is_file(&self) -> bool { fs::metadata(self).map(|m| m.is_file()).unwrap_or(false) } - /// Whether the underlying implementation (be it a file path, or something - /// else) is pointing at a directory in the underlying FS. Will return - /// false for paths to non-existent locations or if the item is not a - /// directory (eg files, named pipes, etc). Follows links when making this - /// determination. + /// Returns whether the path is pointing at a directory. + /// + /// This function will traverse symbolic links to query information about the + /// destination file. In case of broken symbolic links this will return `false`. + /// + /// # Examples + /// + /// ```no_run + /// use std::path::Path; + /// assert_eq!(Path::new("./is_a_directory/").is_dir(), true); + /// assert_eq!(Path::new("a_file.txt").is_dir(), false); + /// ``` #[stable(feature = "path_ext", since = "1.5.0")] pub fn is_dir(&self) -> bool { fs::metadata(self).map(|m| m.is_dir()).unwrap_or(false)