Document that create_dir_all calls mkdir/CreateDirW multiple times

Author: tbu-

library/std/src/fs.rs

@@ -2258,7 +2258,7 @@ pub fn canonicalize<P: AsRef<Path>>(path: P) -> io::Result<PathBuf> {
 /// # Platform-specific behavior
 ///
 /// This function currently corresponds to the `mkdir` function on Unix
-/// and the `CreateDirectory` function on Windows.
+/// and the `CreateDirectoryW` function on Windows.
 /// Note that, this [may change in the future][changes].
 ///
 /// [changes]: io#platform-specific-behavior
@@ -2300,8 +2300,12 @@ pub fn create_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
 ///
 /// # Platform-specific behavior
 ///
-/// This function currently corresponds to the `mkdir` function on Unix
-/// and the `CreateDirectory` function on Windows.
+/// This function currently correspond to calling the directory creation
+/// function for each of the components of the path, starting from the right
+/// and going to the right again after the first successful call. The directory
+/// creation function used on Unix is `mkdir` and `CreateDirectoryW` on
+/// Windows.
+///
 /// Note that, this [may change in the future][changes].
 ///
 /// [changes]: io#platform-specific-behavior