Document that create_dir_all calls mkdir/CreateDirW multiple times

[tbu-]

No description provided.

[rustbot]

r? @Amanieu

rustbot has assigned @Amanieu.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[the8472]

How do those details help the reader?

[tbu-]

It's not a single syscall that makes this function work, but additional logic on top of it. That's interesting for the user of this function.

[the8472]

We don't document all the functions that happen to do more than 1 syscall. So, again, why is that interesting to the user? How does it help them to use it?

[tbu-]

It's interesting in that it's non-atomic. In the error case, there might be partial directory structures lying around.

We don't document all the functions that happen to do more than 1 syscall.

Can you give an example of a function that documents which syscall it corresponds to, but uses it multiple times without documenting it?

[the8472]

It's interesting in that it's non-atomic. In the error case, there might be partial directory structures lying around.

Then the docs should say that, rather then trying to say that through the implementation details.

Can you give an example of a function that documents which syscall it corresponds to, but uses it multiple times without documenting it?

Eh, most docs aren't even that precise. fs::copy says which syscalls it uses but not how often.

[tbu-]

It's interesting in that it's non-atomic. In the error case, there might be partial directory structures lying around.

Then the docs should say that, rather then trying to say that through the implementation details.

Before I'll try to do that: Are you opposed to also mentioning that it's using multiple calls to mkdir instead of just one, in the implementation details? I'll remove the longer explanation of how the multiple calls are issued.

[the8472]

Using a plural is fine. Explaining the traversal order seems unnecessary to me.

[Amanieu]

@bors r+ rollup

[bors]

📌 Commit a0f8ada has been approved by Amanieu

It is now in the queue for this repository.