Add platform support without a version to the @Available directive

[heckj]

Feature Name

Platform-support-without-versioning

Description

Enable the @available directive to define a platform (Linux, Android) without a version, storing the semantic version as 0.0.0 to maintain data structure consistency and allow for the potential of future ABI stability. When a platform is included with a semantic version of 0.0.0, display it as just the platform's name, without citing a version.

The expected feature changes here would be two fold:

• updates to DocC to support additional directive structure that didn't expect a version for a platform, and if so specified, infers & defaults to a version of 0.0.0.
• updates to DocC-Render to react to the platform version of 0.0.0 and display the relevant platform name without a version attached to it.

Forum Discussion: https://forums.swift.org/t/rfc-support-platforms-without-versions-for-the-available-directive/83550

Motivation

Today we can add explicit platform support to the documentation - separate from the @available() mechanisms in the source code - that allow an author to specify intended availability - for a symbol, or to be applied to articles, presented by DocC. For some platforms (Linux, Android, Wasm) there is no version that really applies, as there's no expectation of ABI stability on those platforms. But when you, as an author, want to assert the intent for your package to support Linux, or Android, etc - we should support making it easy to add availability for a platform where there isn't a version (yet) available.

Importance

If the @available C-like macros are used on Swift code, that data will always take precedence for the symbol, but in some cases it's not easy to use those - this allows a developer/author of a package to annotate platform expectations at the documentation level for there code, outside of providing a compiler verified mechanism for the same.

Alternatives Considered

• Status Quo: Leaving the @available() directive as it stands, and displaying either a fake or convention based version that it meaningless in the documentation.

• Revising the Available directive data structure to make the platform version entirely optional. I looked at this path first, and discarded it due to the tendrils of that data - both into DocC itself, processing from a blanket assertion of that kind of information from an Info.plist, and ultimately passed along into the RenderNode data structures that are passed as the core data to DocC-Render to provide this information. It seemed more reasonable to leverage using the Platforms as they stood, building in an expected convention of using 0.0.0, over revising all the code that touched on that processing or the display of that information.

• Related past requests: Add * support for @Available directive #969 build on the expectation that Swift is available everywhere, but don't address the desire for a platform author to assert "Hey, my package explicitly supports Linux" or "My package explicitly doesn't support /name_the_platform_here/"

[grynspan]

See also rdar://163285014.