Merge ref '6bcdcc73bd11' from rust-lang/rust

Pull recent changes from https://github.com/rust-lang/rust via Josh.

Upstream ref: 6bcdcc73bd11568fd85f5a38b58e1eda054ad1cd
Filtered ref: 6cc4ce79e1f8dc0ec5a2e18049b9c1a51dee3221

This merge was created using https://github.com/rust-lang/josh-sync.

1 files changed, 6 insertions, 1 deletions

diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs
index 72ad7c244ee..b3ca118a452 100644
--- a/library/std/src/fs.rs
+++ b/library/std/src/fs.rs
@@ -1111,6 +1111,11 @@ impl File {
     /// `futimes` on macOS before 10.13) and the `SetFileTime` function on Windows. Note that this
     /// [may change in the future][changes].
     ///
+    /// On most platforms, including UNIX and Windows platforms, this function can also change the
+    /// timestamps of a directory. To get a `File` representing a directory in order to call
+    /// `set_times`, open the directory with `File::open` without attempting to obtain write
+    /// permission.
+    ///
     /// [changes]: io#platform-specific-behavior
     ///
     /// # Errors
@@ -1128,7 +1133,7 @@ impl File {
     ///     use std::fs::{self, File, FileTimes};
     ///
     ///     let src = fs::metadata("src")?;
-    ///     let dest = File::options().write(true).open("dest")?;
+    ///     let dest = File::open("dest")?;
     ///     let times = FileTimes::new()
     ///         .set_accessed(src.accessed()?)
     ///         .set_modified(src.modified()?);