async-rs / async-std

Async version of the Rust standard library
https://async.rs
Apache License 2.0
3.97k stars 342 forks source link

Fix docs for `fs::create_dir_all()` #1051

Open riveroon opened 1 year ago

riveroon commented 1 year ago

So... correct me if I'm wrong, but fs::create_dir_all()'s docs seems to have a minor issue - it has the wrong behavior documented:

An error will be returned in the following situations: path already points to an existing file or directory.

However, async_std's create_dir_all() uses std's create_dir_all() internally, which does NOT return an error from an existing path:

Recursively create a directory and all of its parent components if they are missing.

and the DirBuilder::create() (which std::fs::create_dir_all() uses internally) states:

It is considered an error if the directory already exists unless recursive mode is enabled.

This can be demonstrated with the following code:

fn main() {
    async_std::task::block_on(async {
        let x = Path::new("./hello/world");
        println!("{:?}", fs::create_dir_all(x).await);
    });
}

Running the above code twice prints Ok(()) twice, instead of printing an Err(...) after an Ok(()).

As a side note, a statement similar to the one in std's create_dir_all() documentation exists, but is phrased ambiguously, making it look like only the parent directory creation is optional when paired with the bad documentation:

Creates a new directory and all of its parents if they are missing.