Add initial implementation of a consolidated availability logic by d-ronnqvist · Pull Request #1674 · swiftlang/swift-docc

d-ronnqvist · 2026-09-23T10:24:55Z

Bug/issue #, if applicable: rdar://172280267

Summary

This PR adds an alternate implementation to DocC's availability logic that's consolidated in one place. This type isn't integrated yet, so it is effectively dead code.

Matching behavior

The new implementation tries quite hard to preserve all behaviors of the current implementation, even when those behaviors are inconsistent or are otherwise bugs. The two exceptions to this are (from AvailabilityTests.swift):

withKnownIssue("iPadOS availability should follow iOS availability (rdar://173704351)") { ...

// FIXME: Some availability logic only happens when symbols have declarations (rdar://172280267)

which were too quirky and inconsistent for me to be able to replicate their fully behaviors.

However, nothing changes until we integrate this new implementation.

No integration yet

With the goal of making this PR smaller and easier to review I haven't included the changes that integrate this new consolidated availability implementation throughout DocC.

However, there's also a risk that by omitting the integration, reviewers may have a harder time seeing the bigger picture.

Let me know if you prefer that I push the integration changes to this PR or to a follow-up PR.

Dependencies

None.

Testing

Nothing in particular unless we prefer to rescope this PR to also include the integration.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

Added tests
Ran the ./bin/test script and it succeeded
Updated documentation if necessary

patshaughnessy

Amazing work so far - can't wait to see where you go with this!

I assume unit tests will come later? Or will the existing unit test coverage test this automatically when we start using it?

patshaughnessy · 2026-09-23T22:30:44Z

+        }
+    }
+
+    func preservingBugThatArticlesDoNotDisplayDefaultAvailability() -> Self {


Is the idea we will call this later, for articles only?

Yes, the integration calls this for the common base value for articles.

patshaughnessy · 2026-09-23T22:33:19Z

+        for module in unifiedGraph.moduleData.values {
+            guard let knownPlatform = KnownPlatform(module.platform) else {
+                // We only care about tracking known values for symbol graph's platforms.
+                continue


Should we add a debug assertion here, for the case we ever receive an unknown platform from the unified symbol graph?

No. There can be unknown platforms but AFAICT the current implementation doesn't track them.

patshaughnessy · 2026-09-23T22:35:31Z

+        // Any platform that's left as `havePlatformForInSymbolGraph` after this loop indicates a platform that the symbol was excluded from using conditionally compilation.
+        for selector in unifiedSymbol.allSelectors where selector.interfaceLanguage == languageFilter {
+            guard let selectorPlatform = KnownPlatform(selector) else {
+                continue


Same here: debug assertion?

I don't think so. There can be unknown platforms but AFAICT the current implementation doesn't track them.

patshaughnessy · 2026-09-23T22:39:34Z

+                        )
+                    }
+                } else if let domainName = availability.domain?.rawValue {
+                    customPlatformsByName[domainName] = if availability.isUnconditionallyUnavailable || availability.obsoletedVersion != nil {


Ah so symbol graphs can contain unknown platforms?

The selector platform and the specified domain name of an in-source attribute are two different things.

patshaughnessy · 2026-09-23T22:44:03Z

+
+    /// Finished computing the combined availability information by applying "fallback" behaviors for iPadOS and Mac Catalyst.
+    mutating func finalizePlatformFallbacks() {
+        let valueToCopy = knownPlatforms[.iOS]


Maybe add "iOS" into the identifier valuetToCopy to make the following code easier to follow.

I don't know. For me it doesn't matter much to this where the value came from, only that it's the value that's copied for the other fallbacks.

patshaughnessy · 2026-09-23T22:53:41Z

+    ///
+    /// A page as a whole is considered to be deprecated if the API is deprecated on all the platforms that the API is available for.
+    var isDeprecated: Bool {
+        return knownPlatforms.allSatisfy {


Will this work correctly when there are no platforms? Or if all the platforms are unavailable?

Should we add a guard similar to above in isBeta?

If it doesn't we don't have any test coverage from that elsewhere in DocC.

Is there a list of things we'd like to clean up about the availability behavior once this consolidated logic is merged? Maybe it's worth adding a test for this.

I added two tests for this in cc6941f

Also, fix minor typo in code comment.

…tion code

d-ronnqvist · 2026-09-24T09:37:18Z

[...] can't wait to see where you go with this!

Would it be easier or harder to review this new implementation if I also pushed the code that integrates it the same PR (compared to posting a follow up PR with the integration changes)?

I assume unit tests will come later? Or will the existing unit test coverage test this automatically when we start using it?

I've been adding tests covering the availability logic for months, primarily in

0d8caef ("Add lots of test covering a variety of current availability behaviors")
c3c1b85 ("Add more availability tests")
b8a30e3 ("Add even more availability tests")

Like I mentioned in that first PR; the goal of those tests was to gain coverage of the observable behaviors of the current implementation so that the planned new implementation could keep the same behaviors. The idea is that by integrating this new code and using it to compute the values that are observable in the rendered output, we can verify that every behavior that those tests cover remain the same.

…esn't

…ailability domain

mayaepps

This looks good to me. I personally found it easier to review with just these changes in this PR, rather than also including the integration. You could consider opening a second PR targeting this branch with the integration, if you'd prefer to ultimately merge both into main at the same time.

mayaepps · 2026-09-28T23:14:28Z

+    ///
+    /// - Parameter defaultAvailability: The decoded "default" availability, or `nil` if the inputs don't specify any "default" availability.
+    init(defaultAvailability: [DefaultAvailability.ModuleAvailability]?) {
+        knownPlatforms = [Information](repeating: Information(state: .unavailable, source: .initialValue), count: KnownPlatform.wildcard.rawValue + 1 /* once for all known platforms */)


Is space-efficiency the reason you're not using a dictionary here?

It's part of the reason but I'm also trying to avoid unnecessary work of sorting the platforms when there's a known list of values and the expected order is known beforehand.

mayaepps · 2026-09-28T23:22:46Z

+    ///
+    /// This is its own method because this computation only needs to be performed once per module.
+    /// Alternatively, if `addInSourceAvailability(from:languageFilter:)` was responsible for this task,
+    /// then the caller couldn't forget to perform this task but it would have to performed once per symbol instead once per module.


nit:

Suggested change

/// then the caller couldn't forget to perform this task but it would have to performed once per symbol instead once per module.

/// then the caller couldn't forget to perform this task but it would have to be performed once per symbol instead once per module.

Note also the parameter documentation below has an unfinished sentence.

Both fixed in 43cf666

mayaepps · 2026-09-28T23:42:38Z

+    ///
+    /// - Parameters:
+    ///   - unifiedSymbol: The symbol to read the unified in-source availability annotations from.
+    ///   - languageFilter: The string identifier of a source language, that that container used to restrict the container to only add information that matches the provides  which information the container reads from the symbol.


nit: I'm having a bit of trouble understanding this one, could you re-phrase?

I rephrased this in 43cf666

mayaepps · 2026-09-29T00:16:57Z

+                case "watchos":         self = .watchOS
+                case "tvos":            self = .tvOS
+                case "visionos":        self = .visionOS
+                default:                return nil


Should we warn if there is a platform in the symbol graph that we don't know about?

I don't think so. Similar to this question there can be unknown platforms but AFAIC the old platform didn't care about them. (We also have lots of tests that don't specify a platform for the symbol graph.)

mayaepps · 2026-09-29T00:21:42Z

+            patch = .init(clamping: version.patch)
+        }
+
+        ///


Suggested change

///

…ecated

d-ronnqvist · 2026-09-29T08:47:43Z

@swift-ci please test

d-ronnqvist · 2026-09-29T08:50:23Z

The integration can be merged after this. In the mean time, this will be "dead" / unused code.

d-ronnqvist added 2 commits September 23, 2026 12:04

Initial implementation of a consolidated availability logic

e9d2769

Merge branch 'main' into consolidated-availability

8025de3

patshaughnessy reviewed Sep 23, 2026

View reviewed changes

d-ronnqvist added 6 commits September 24, 2026 10:30

Match symbol graph module's platform names case insensitively

1aa3e0c

Finish incomplete abstract in documentation comment

ff9a674

Also, fix minor typo in code comment.

Privately extract and reuse common platform creation code

fe5cd82

Privately extract and reuse common info from in-source attribute crea…

bec4147

…tion code

Merge branch 'main' into consolidated-availability

0ff6b2c

Add abstract for makePlatforms(...)

de971d3

d-ronnqvist added 3 commits September 24, 2026 11:44

Handle platform names that Metadata.Availability.Platform itself do…

b7ced1e

…esn't

Elaborate in code comment about why there's no iPadOS symbol graph av…

a180fb1

…ailability domain

Handle iPadOS as its own beta platform without the iOS fallback

fc12c23

d-ronnqvist marked this pull request as ready for review September 24, 2026 11:36

d-ronnqvist requested a review from a team as a code owner September 24, 2026 11:36

d-ronnqvist mentioned this pull request Sep 28, 2026

Improve deprecation in markdown export #1675

Open

2 of 3 tasks

mayaepps approved these changes Sep 29, 2026

View reviewed changes

d-ronnqvist added 3 commits September 29, 2026 09:34

Merge branch 'main' into consolidated-availability

d05af88

Tidy up some documentation comments

43cf666

Add tests that pages without availability info aren't considered depr…

cc6941f

…ecated

d-ronnqvist enabled auto-merge (squash) September 29, 2026 08:49

d-ronnqvist merged commit f5511ec into swiftlang:main Sep 29, 2026
42 checks passed

d-ronnqvist deleted the consolidated-availability branch September 29, 2026 11:31

	/// then the caller couldn't forget to perform this task but it would have to performed once per symbol instead once per module.
	/// then the caller couldn't forget to perform this task but it would have to be performed once per symbol instead once per module.

Conversation

d-ronnqvist commented Sep 23, 2026

Summary

Matching behavior

No integration yet

Dependencies

Testing

Checklist

Uh oh!

patshaughnessy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist Sep 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

d-ronnqvist commented Sep 24, 2026

Uh oh!

mayaepps left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist commented Sep 29, 2026

Uh oh!

d-ronnqvist commented Sep 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

d-ronnqvist Sep 24, 2026 •

edited

Loading