Rollup merge of #69284 - jumbatm:openoptions-create-doc, r=Dylan-DPC

Reword OpenOptions::{create, create_new} doc.

Closes #69254.

Currently, the doc comment for `fs::OpenOptions::create` doesn't mention its behaviour when opening an existing file, and `fs::OpenOptions::create_new`'s doc comment is worded in a way that doesn't make it clear that it actually _fails_ if the file already exists, not overwrite the existing file with a new one.

This PR addresses addresses this by rewording the doc comments to be more explicit.

r? @GuillaumeGomez

1 files changed, 4 insertions, 8 deletions

diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index cff7bbe5ef1..09be3f13050 100644
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -844,10 +844,7 @@ impl OpenOptions {
         self
     }
 
-    /// Sets the option for creating a new file.
-    ///
-    /// This option indicates whether a new file will be created if the file
-    /// does not yet already exist.
+    /// Sets the option to create a new file, or open it if it already exists.
     ///
     /// In order for the file to be created, [`write`] or [`append`] access must
     /// be used.
@@ -868,11 +865,10 @@ impl OpenOptions {
         self
     }
 
-    /// Sets the option to always create a new file.
+    /// Sets the option to create a new file, failing if it already exists.
     ///
-    /// This option indicates whether a new file will be created.
-    /// No file is allowed to exist at the target location, also no (dangling)
-    /// symlink.
+    /// No file is allowed to exist at the target location, also no (dangling) symlink. In this
+    /// way, if the call succeeds, the file returned is guaranteed to be new.
     ///
     /// This option is useful because it is atomic. Otherwise between checking
     /// whether a file exists and creating a new one, the file may have been