Doc: file/open docs a bit confusing

[ChanderG]

This is more of a comment than an issue, but the docstring for the file/open function is a bit unclear: https://github.com/janet-lang/janet/blob/3a4d56afca2eee0e4dbca9a6400757d198e6d6f3/src/core/io.c#L133

I wanted to read/write a file and none of the obvious combinations of "w" and "a" with flags seemed to work. Seeing that the code was directly using the mode keyword with fopen and looking at the man page of fopen made it immediately clear that what I wanted was r+ - but this is not clear from the janet function documentation.

[sogaiu]

Yes, I agree.

One idea to improve the situation might be to modify file/open's docstring so that it mentions looking at fopen's documentation for further details.

[sogaiu]

Perhaps a PR can be created to add something like the following as the last bit of the docstring:

See fopen (<stdio.h>, C89, C99) for further details.

[CosmicToast]

Probably C99 only, since Janet explicitly targets C99. C89 is quite different on the overall.

[sogaiu]

@CosmicToast Thanks for taking a look and the feedback.

I wrote C89 because I found the following in fopen(3):

CONFORMING TO
       fopen(), freopen(): POSIX.1-2001, POSIX.1-2008, C89, C99.

Good point about Janet targetting C99 -- not mentioning C89 also makes things shorter :)

Then if folks are good with:

See fopen (, C99) for further details.

I'll open a PR.

[sogaiu]

@ChanderG It looks like #1231 was merged.

Does it look like this issue has been resolved? If so, may be it can be closed :)