I'd like to provide some more background for the discussion here, as well as some specific recommendations.
Right now, when an API or module has availability information, DocC shows the platform availability as a set of "pills" showing platform and version. For example, here's what we show for the SwiftSyntax module on the package index:
While this information is not wrong, it is incomplete and therefore gives the wrong impression. This package and module work on every platform Swift supports, but it looks like it is only available on Apple platforms. We've received feedback about this being confusing for developers who don't know if a given Swift package works on Linux or Windows.
Swift's availability syntax was intentionally designed with an explicit * to indicate that something is assumed available on every platform that isn't explicitly mentioned. So an API expressed like this:
@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
public func f() { }
is available on all platforms. On macOS, you need macOS 10.15. On iOS, you need iOS 13.0, etc.
I think DocC needs the equivalent of the * to clarify that code works on all platforms. This is achievable on the module level by adding a custom entry to the CDAppleDefaultAvailability array in the Info.plist, e.g.,
<dict>
<key>name</key>
<string>All Swift Platforms</string>
<key>version</key>
<string>5.1</string>
</dict>
Recommendation #1: we come up with a canonical spelling and version to represent "everywhere that Swift works." Here, I've used "All Swift Platforms" and the minimum supported Swift version (in this case 5.1).
Once we have an agreed-upon spelling, we should find a way to get this change to ripple through the package ecosystem. We have a few tools at our disposal to do this, in order of increasing aggressiveness:
- We can document that this is best practice and socialize it
- We can have DocC warn when there are
CDAppleDefaultAvailability entries but none for "All Swift Platforms"
- We can have DocC infer an "All Swift Platforms" entry if none was provided. The only hard part here is inferring a version number. It's possible to map backwards from (say) iOS or macOS version numbers of the corresponding Swift runtime version.
Doing (2) and (3) probably require some opt-out mechanism to silence the warning / inference by adding another entry somewhere in the Info.plist.
Recommendation #2: pick one of the more aggressive tools to get "All Swift Platforms" to ripple through the ecosystem quickly. (2) effectively matches what the compiler does with availability, so that one is easy.
Recommendation #3: We should rename the CDAppleDefaultAvailability key to CDDefaultAvailability. Availability is not an Apple-only concept, even though we currently only define ABI stability on Apple platforms.
As a bonus topic, there's another semi-platform coming up that could similarly benefit from having a standardized spelling for availability: Embedded Swift. It does take work to get a package to build with Embedded Swift, so it needs to be opt in.
Recommendation #4: Standardize on "Embedded" as the platform name for a library that supports Embedded Swift, where the version is the minimum Swift version.
Doug
