Document why DirExt::access on Windows doesn't use their faccess equivalent

[ssokolow]

I noticed that your Windows implementation of DirExt::access just tries opening the file.

I understand if _access, _waccess, t_access or _access_s, _waccess_s, _taccess_s from the Microsoft C Runtime impose additional dependencies you want to avoid, and that the Win32 API-native version's overcomplicated credentials blow up to six pages in the faccess crate's Windows implementation (Link to the source file, MIT-licensed) once you address various edge cases.

However, I was unable to find any clear documentation for the rationale behind that. (Which I'm guessing is "auditing burden".)

Could that be improved, please?

[ChrisDenton]

I understand if _access, _waccess, t_access or _access_s, _waccess_s, _taccess_s from the Microsoft C Runtime impose additional dependencies you want to avoid

Those functions don't check access. They merely check if the readonly attribute is set or not (or in the case of directories, not even that). It's roughly equivalent to the standard library's Permission::readonly.

Opening a file is an effective way of testing access. And a lot cheaper than opening the file and handling ACLs.

[ssokolow]

The Microsoft documentation did seem a little confused on those functions, with some parts saying they check read-only status and other parts seeming to say the mode argument worked beyond that.

Either way, I'm not asking to use them. I'm asking for the cap-std documentation to be clear on why this approach was chosen.