path_open anchor is re-used between the flag and the function

[codefromthecrypt]

path_open anchor points to the function:

https://github.com/WebAssembly/WASI/blob/main/phases/snapshot/docs.md#path_open

This makes the following text easy to be confused:

fd_datasync: bool The right to invoke fd_datasync. If path_open is set, includes the right to invoke path_open with fdflags::dsync.
https://github.com/WebAssembly/WASI/blob/main/phases/snapshot/docs.md#record-members

Because when you click on the link that's implied as a flag, it goes to the function. Unless you scroll around to find that fd_open is also a right, or look closely at the word "invoked" and infer the mistake, brain breaks a bit.

Correcting the anchors somehow or prefixing right flags with "flag_" or "right_" can sort this out

[sunfishcode]

Yes, the whole "rights" system in WASI is derived from CloudABI, and the consensus from both users and implementors is overwhelmingly that it's complex, confusing, and not worth it to continue supporting. I've removed it from the latest wasi-filesystem.

[codefromthecrypt]

good advice. thanks. I wish there was a place to know the "minimum viable API" for snapshot1, though, as there are code using it and would prefer not to burn time on cul-de-sacs.. any ideas?

[sunfishcode]

My best idea right now is to just ask questions here in this issue tracker, whenever you find yourself about to do something complex, to find out whether you need to do it or not. We're working on getting to a better place, where we can have better docs, but WASI is a fairly complex place right now, with all the changes that have happened in the layers underneath it, so for now, this is my best idea.

[codefromthecrypt]

Thanks tons, and appreciate the candor! I'll close this one for now as targeted issues are better.