From d25d6c5bd8c211a5e606b2ac37bbecb9be1ac12b Mon Sep 17 00:00:00 2001
From: Alexis Bourget <alexis.bourget@gmail.com>
Date: Sat, 27 Jun 2020 18:10:58 +0200
Subject: [PATCH] Update the documentation to point to open instead of is_file
 and is_dir

---
 src/libstd/fs.rs   | 24 ++++++++++++++----------
 src/libstd/path.rs |  2 +-
 2 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index a9c481dfb809f..23bd8f6498b4a 100644
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -1033,14 +1033,16 @@ impl Metadata {
     /// [`is_dir`], and will be false for symlink metadata
     /// obtained from [`symlink_metadata`].
     ///
-    /// This property means it is often more useful to use `!file_type.is_dir()`
-    /// than `file_type.is_file()` when your goal is to read bytes from a
-    /// source: the former includes symlink and pipes when the latter does not,
-    /// meaning you will break workflows like `diff <( prog_a ) <( prog_b )` on
-    /// a Unix-like system for example.
+    /// When the goal is simply to read from (or write to) the source, the most
+    /// reliable way to test the source can be read (or written to) is to open
+    /// it. Only using `is_file` can break workflows like `diff <( prog_a )` on
+    /// a Unix-like system for example. See [`File::open`] or
+    /// [`OpenOptions::open`] for more information.
     ///
     /// [`is_dir`]: struct.Metadata.html#method.is_dir
     /// [`symlink_metadata`]: fn.symlink_metadata.html
+    /// [`File::open`]: struct.File.html#method.open
+    /// [`OpenOptions::open`]: struct.OpenOptions.html#method.open
     ///
     /// # Examples
     ///
@@ -1313,14 +1315,16 @@ impl FileType {
     /// [`is_dir`] and [`is_symlink`]; only zero or one of these
     /// tests may pass.
     ///
-    /// This property means it is often more useful to use `!file_type.is_dir()`
-    /// than `file_type.is_file()` when your goal is to read bytes from a
-    /// source: the former includes symlink and pipes when the latter does not,
-    /// meaning you will break workflows like `diff <( prog_a ) <( prog_b )` on
-    /// a Unix-like system for example.
+    /// When the goal is simply to read from (or write to) the source, the most
+    /// reliable way to test the source can be read (or written to) is to open
+    /// it. Only using `is_file` can break workflows like `diff <( prog_a )` on
+    /// a Unix-like system for example. See [`File::open`] or
+    /// [`OpenOptions::open`] for more information.
     ///
     /// [`is_dir`]: struct.FileType.html#method.is_dir
     /// [`is_symlink`]: struct.FileType.html#method.is_symlink
+    /// [`File::open`]: struct.File.html#method.open
+    /// [`OpenOptions::open`]: struct.OpenOptions.html#method.open
     ///
     /// # Examples
     ///
diff --git a/src/libstd/path.rs b/src/libstd/path.rs
index 35f6b5838a92a..fa54b2063b424 100644
--- a/src/libstd/path.rs
+++ b/src/libstd/path.rs
@@ -2506,7 +2506,7 @@ impl Path {
     /// check errors, call [`fs::metadata`] and handle its Result. Then call
     /// [`fs::Metadata::is_file`] if it was Ok.
     ///
-    /// Note that the explanation about using `!is_dir` instead of `is_file`
+    /// Note that the explanation about using `open` instead of `is_file`
     /// that is present in the [`fs::Metadata`] documentation also applies here.
     ///
     /// [`fs::metadata`]: ../../std/fs/fn.metadata.html