async-rs / async-rs/async-std

Fix docs for `fs::create_dir_all()`

Open
#1,051 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
4.1k
Forks
339
PR merge metrics
No merged PRs in 30d

Description

So... correct me if I'm wrong, but [`fs::create_dir_all()`](https://docs.rs/async-std/latest/async_std/fs/fn.create_dir_all.html)'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()`](https://doc.rust-lang.org/std/fs/fn.create_dir_all.html) 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()`](https://doc.rust-lang.org/std/fs/struct.DirBuilder.html#method.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:
```rust
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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.