Allow documentation to reference Swift stdlib symbols

[ktoso]

Feature Name

Reference Swift stdlib symbols

Description

This is related to Allow combined documentation of multiple targets #255 but specific about libraries shipped with Swift. This includes libraries such as Swift, _Concurrency and Distributed and there is increasingly more of those -- like regex builders etc.

Those modules are "well known" and it should be possible, unless some dependency "shadows" it, to refer to e.g. Concurrency/Task and that link should direct to a well known place where those docs for stdlib are -- likely on apple.com etc.

Motivation

As we develop more concurrency, and distributed actor libraries, a lot of them are refering to Task and other types declared in Swift, but our library docs cannot point developers to their documentation efficiently.

Importance

Important for a cohesive developer experience using Apple (and non-apple) developed libraries.

Alternatives Considered

No response

[d-ronnqvist]

To try and set expectations:

I view linking to Swift standard library symbols as the same problem as the "Linking to symbols in SDKs and other pre-built dependencies." future diction that's mentioned in the "Combined documentation of multiple targets" forum post.

What that means for this issue is that we view it as an important enhancement but we'll want to deliver the core support for combined documentation of multiple targets before making any serious progress on this.

[ktoso]

Yeah that's fine, the multiple-targets is the most important thing; I was talking with @franklinsch yesterday about features and this came up so I promised to file issues :)

[Kyle-Ye]

Hi @ktoso . A current workaround in my experience is to manually use hardcoded link in you documentation.

- <doc://com.apple.documentation/documentation/Swift/AsyncSequence> // Apple
- <doc://com.apple.documentation/documentation/Swift/Never> // Apple
+ [AsyncSequence](https://developer.apple.com/documentation/Swift/AsyncSequence) // Other package
+ [Never](https://developer.apple.com/documentation/Swift/Never) // Other package

I assume when Apple is releasing their SDK, they may use some trick such as external-resolver so that they can reference AsyncSequence as <doc://com.apple.documentation/documentation/Swift/AsyncSequence> directly in their SDK's Swift file.

But currently for our 3rd party developer, we can manually use such link([AsyncSequence](https://developer.apple.com/documentation/Swift/AsyncSequence)) as a workaround to provide the same experience as Apple.

• Go to Apple's documentation site when viewing on web
• Go to corresponding doc page when viewing in Xcode docuemntation

[ktoso]

Sure, hardcoding is a workaround; this is a feature request to support this properly.

[Kyle-Ye]

I'm expecting we public the external-resolver thing of Apple is using internally as a public tool. So that we can achieve the feature by using

https://github.com/apple/swift-docc/blob/main/Sources/SwiftDocC/Infrastructure/External%20Data/ExternalSymbolResolver.swift

docc ... \
    -external-resolver /path/to/apple-doc-resolver

The apple-doc-resolver will receive request from external bundle com.apple.documentation and respond them as https://developer.apple.com/documentation