swiftlang / swiftlang/github-workflows
Docs soundness check fails in the vicinity of platform-specific API
Nobody has claimed this yet.
- Dominant language
- Swift
- Stars
- 115
- Forks
- 57
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 3
Description
The docs soundness check runs on Linux currently. Swift Testing has some Apple-specific API (and some Windows-specific API) and our DocC bundle contains some references to symbols that are marked @available(unavailable) on Linux. As a result, when we build our DocC bundle on Linux, those symbols are called out as missing. When we run the soundness check, it fails outright.
We need some general way to solve this problem for packages/targets/etc. that have platform-specific API variation. I'm not sure what a good solution looks like here. I don't know if that means making a change in swift-docc to introduce something like #if, or if it means having the soundness check run for multiple targets and combine results, or set a Swift compiler condition during the build that we can use to "opt out" some code from the check, or…
This problem isn't specific to Swift Testing: swift-system and swift-subprocess are also impacted, for example.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Linux DocC bundle build and the soundness check described in the issue, focusing on references to symbols marked @available(unavailable) on Linux. Compare how the check could handle platform-specific API across the mentioned package and target variations, and consider the possible approaches listed in the issue. Done means the check no longer fails incorrectly for valid platform-specific documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- ci-cd, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100