swiftlang / swiftlang/github-workflows

Docs soundness check fails in the vicinity of platform-specific API

Open
#166 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.