Filesystem API needs more documenation

[Diggsey]

A lot of the filesystem API is not explicit about its behaviour. This includes:

• Will operations silently overwrite files/directories, or fail instead?
• Platform-specific semantics
• Which underlying OS APIs are used
• What the result of a failed operation might be (for example, deleting a directory might fail with some files being deleted and others not)

Without this documentation it makes it very difficult to write robust tools which access the filesystem, especially if they have to be cross-platform. There also seem to be several places where the library could attempt to be more consistent across platforms.

A simple example is what happens in the case of symlinks. On linux, you delete a directory symlink the same way you delete a file, whereas on windows you should delete it the same way you'd delete a directory. It would be useful if there was a safe way to delete a directory symlink that is both cross-platform, and is guaranteed not to delete the contents of the directory.

Another example is renaming: can you rename a directory onto another? It doesn't seem so, but you can't just delete the destination first, in case the source == the destination, in which case you'll delete the wrong files! But at the same time, there's no way to test paths for equality reliably.

edit:
Another example: how relative paths are treated when creating a symlink. Is a relative path resolved before creating the symlink, or afterwards? Is that true on all platforms?

[retep998]

There is a relatively simple technique to determine whether two files are identical. I could write a PR adding such a method if it can be decided what such a function should be called and where to provide it.

[steveklabnik]

Platform-specific semantics
Which underlying OS APIs are used

These are things which we don't necessarily want to document, as it commits us to a certain kind of stability.

In general, I agree with you, but this section of the API hasn't had any real specific docs work done on it yet, so yeah, it's gonna be a bit under-done at the moment. Anyone who wants to help with this, please let me know!

[retep998]

Which underlying OS APIs are used

If Rust ever intends to support Windows store apps or universal apps then it'll need to be able to use app versions of many system APIs like CreateFile2 instead of CreateFile, so many of the OS APIs that are used will likely differ across targets on Windows. So any documentation should be careful to not describe it as a commitment or guarantee.

[steveklabnik]

part of #29356

[steveklabnik]

Triage: no change

[steveklabnik]

Triage: this is very similar to #24795 , but for std::fs rather than std::io. Its status is the same #24795 (comment)

[steveklabnik]

Given that #24795 was closed, I'm also going to close this. There are some parts of this issue that are not identical to that issue, but a vague list from 2015 isn't useful. If there's anything that needs to be clarified in specific API docs, please open new, detailed issues. Thanks!