Add docstring to constants in Base.Filesystem

[lgoettgens]

A first step towards #52725 for Base.Filesystem.

The type of combined docstring was inspired by

julia/base/libdl.jl

Lines 33 to 46 in 72d3abe

	"""
	RTLD_DEEPBIND
	RTLD_FIRST
	RTLD_GLOBAL
	RTLD_LAZY
	RTLD_LOCAL
	RTLD_NODELETE
	RTLD_NOLOAD
	RTLD_NOW
	Enum constant for [`dlopen`](@ref). See your platform man page for details, if
	applicable.
	"""
	(RTLD_DEEPBIND, RTLD_FIRST, RTLD_GLOBAL, RTLD_LAZY, RTLD_LOCAL, RTLD_NODELETE, RTLD_NOLOAD, RTLD_NOW)

cc @stevengj

[vtjnash]

The details actually come from here https://docs.libuv.org/en/v1.x/fs.html#file-open-constants if you want to link or copy that here

[lgoettgens]

The page doesn't explain all of them, so I rather not link it here

[vtjnash]

Which is missing? I am also a maintainer of that documentation, so it would help to know if one is missing from it

[lgoettgens]

ASYNC, CLOEXEC, LARGEFILE, PATH, RSYNC, TMPFILE are missing from the libuv docs.
And there are some in the libuv docs that are not there in julia.
But if you say that this is the ultimate docu for this, I'll add a link to the docstring.

Suggested change

	See your platform man page for details, if applicable.
	See [the libuv docs](https://docs.libuv.org/en/v1.x/fs.html#file-open-constants) for more details.

[vtjnash]

We should probably delete ASYNC, CLOEXEC, LARGEFILE, and RSYNC exports from our list, since we neither define nor support any of those either. Looks like O_PATH and O_TMPFILE are the only (linux-specific) ones we might pass through successfully, so we could put an asterisk next to those noting they are linux-only.

[stevengj]

This is not an "enum" in the sense of a Julia @enum value. They are just UInt32 constants.

(For some reason, JL_O_TMPFILE is a UInt16, though?? Is this a bug?)

[vtjnash]

yeah, a lot of these are defined incorrectly now, including being the wrong type in some cases, and that they don't follow the UV names that are now consistently defined for them instead our current ad-hoc definitions

[vtjnash]

Just a subtle issue that only a more primitive docs macro is available now which can only handle simpler forms of docs. I have edited it to the simpler form of this, which I think should work, based on testing:

julia> Core.atdoc = Base.CoreDocs.docm

julia> @doc "foo docs" (:foo,)

julia> Core.atdoc = Base.Docs.docm

julia> Base.Docs.loaddocs(Core.Compiler.CoreDocs.DOCS)

[vtjnash]

The tests seem to indicate a few a still missing:

  Expression: undoc == [:File, :Filesystem, :cptree, :futime, :rename, :sendfile, :unlink]
2024-02-10 08:06:10 UTC	   Evaluated: [:File, :Filesystem, :JL_O_FSYNC, :JL_O_NDELAY, :JL_O_NOFOLLOW, :cptree, :futime, :rename, :sendfile, :unlink] == [:File, :Filesystem, :cptree, :futime, :rename, :sendfile, :unlink]