Since Swift 5.8, DocC has included an @Available directive that allows an author to assert availability where the information isn't provided by the underlying symbols graphs. With Swift 6.0, it was enhanced to include a deprecated parameter as well.
This support has been great for platforms where version information is relevant, but has been less effective for platforms where versions don't exist - in particular Linux, Windows, and more recently the Android and WASM platforms.
My intent with this proposal is to make it easier for a package author to assert expectations for people using the package through its documentation. This doesn't do anything to validate the claim, but especially for areas where a package is building on a platform-specific SDK and wants to be able to assert "I only work here and here", there's not many other good options available.
I'd like to pitch/propose a small modification - more of a convention - to make it easier for a package author to assert "I expect this to work on ...some... platform".
To enable this, I'd like to update the DocC Directive to allow Platform to be described without a version, which would default to creating a semantic version of 0.0.0 which would then be encoded where it's expected in the relevant fields. Additionally, update the render display logic in DocC-Render to alternately render any availability detail with a version of 0.0.0 to just display it as the platform name, minus the version information.
I briefly brought up this idea at the last Documentation Tooling workgroup meeting. I'd like to socialize this more broadly and see if there's any horrible gaps in enabling and encoding this convention for our more general use.
Using 0.0.0 provide a valid semantic version that doesn't preclude updating down the road, should versions become relevant, and would order as expected for all the corner cases where we're trying to relate this as optional.
Swift Testing needs this to correctly describe certain features that are supported on e.g. Linux. We want to say "this feature works on Linux" but have no version to stick on the end, and doing something silly like hard-coding "1.0" is inelegant.
I feel like especially for Linux you wouldn't make something available for the whole "Linux platform". It's so hard or even impossible to define, because almost nothing in user space targets a Linux kernel without a libc. What you really want is to declare availability for a particular libc, like Glibc or Musl, and those are versioned.
With Wasm though there are versions (both versions of the W3C standard and versions of the Lime compiler target) and feature sets, so again @Available(Wasm) would barely help.
Then there's WASI, which also has separate versions and subspecs that can be combined arbitrarily. Thus @Available(WASI) is probably better than nothing, but what we really want is @Available(WASI, 0.1) and even @Available(WASI, 0.2, Sockets, Clock, Crypto).
Some more background: Apple's documentation already allows for platform-without-version when published on developer.apple.com. See for example the documentation for#expect() which lists macOS, iOS, etc. without version numbers because #expect() is available on those platforms and is de facto back-deployed. There's no way for documentation bundles to do that for non-Apple platforms today.
We have features that are available on Linux anywhere Swift is available on Linux, and so we want to document that the feature is available on Linux, but we don't have a Linux version constraint.
(Linux is an example here: the same sort of constraint applies to Windows[1], FreeBSD, Android, etc.)
This proposal in no way prevents you from writing@Available(Glibc 2.31) or similar in your DocC markup if you have a glibc-version-specific constraint.
There is no mechanism to query the version of WASI/Wasm for which Swift code is being compiled or under which Swift code is running, so saying "this feature is only available with WASI 0.2" isn't meaningful in Swift (at this time). I would love to be able to write #if WASI(>=0.2) or if #available(WASI 0.2, *) or some such.
Yes, we could just hard-code "11" these days, but keep reading. âŠī¸
I think you'd want both versioned and versionless availability constraints for the BSDs, since the libcs are more tightly coupled to operating system version releases than on Linux. Though in practice, I'm not sure there'd be much call for having applications that are needing to expose documentation differences keyed on libc differences...but that could just be a failure in my creativity.