Improve documentation for `std::fs::DirBuilder`

diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index ca26dc9527c041e86061ff9c1f11ffbec73827f4..1b00eb95de2bc434340918ffeeda17c62d2ce8db 100644 (file)
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -1726,9 +1726,9 @@ pub fn new() -> DirBuilder {
         }
     }
 
-    /// Indicate that directories create should be created recursively, creating
-    /// all parent directories if they do not exist with the same security and
-    /// permissions settings.
+    /// Indicates that directories should be created recursively, creating all
+    /// parent directories. Parents that do not exist are created with the same
+    /// security and permissions settings.
     ///
     /// This option defaults to `false`.
     ///
@@ -1749,6 +1749,9 @@ pub fn recursive(&mut self, recursive: bool) -> &mut Self {
     /// Create the specified directory with the options configured in this
     /// builder.
     ///
+    /// It is considered an error if the directory already exists unless
+    /// recursive mode is enabled.
+    ///
     /// # Examples
     ///
     /// ```no_run