create_dir_all doc is unclear

[Stargateur]

If any directory in the path specified by path does not already exist and it could not be created otherwise. The specific error conditions for when a directory is being created (after it is determined to not exist) are outlined by fs::create_dir. source

Is very unclear for me. I think a clarification wouldn't hurt. Does this mean "If a directory doesn't exist and can't be create" ?

Notable exception is made for situations where any of the directories specified in the path could not be created as it was being created concurrently. Such cases are considered to be successful. That is, calling create_dir_all concurrently from multiple threads or processes is guaranteed not to fail due to a race condition with itself.

"could not be created as it was being created concurrently" is also not very clear.

Overall, I think this doc could be rewrite using more straightforward sentence, and more simple english.

[saminoorsyed]

Hi,

I'm a little new to OSS and was looking for an easy place to get started contributing. I'll also submit a PR request if that's easier to review. I'm still getting familiar with Rust documentation and resources, so sorry in advance if I step on toes!

I know this issue was created a while ago, but it looks like the wording has not yet been changed in the official docs. Here's what I was thinking in terms of how to change the wording from above:

---

This function will return an error in the following situation, but is not limited to just this case:

• Any directory in the path does not already exist and could not be created. The specific error conditions for creating a directory after it is determined to not exist are outlined by fs::create_dir.

A notable exception is made for any directories in the specified path that cannot be created because a concurrent process is creating those same directories. Such cases are considered to be successful; Calling create_dir_all is guaranteed to not fail as a result of a race condition with itself.

---

Here are the changes I made + the reasoning:

1. I corrected the first sentence by making it singular instead of plural since there is only one situation listed
2. I reduced the verbiage of the second section so that it was more direct and less redundant.
3. I adjusted the wording in the last paragraph to be more streamlined. The use of a semicolon implies that the sentence before and after make similar points.

Thanks for your time and energy reviewing this!

--Sami

[tgross35]

@saminoorsyed for future reference, just submit suggested changes as a PR where they can get reviewed and picked up :) It looks like #126548 covers this now.