Linking between frameworks

Hey,

One feature I've found been trying to discover in docc is the ability to add links or references to symbols that belong to a separate Swift target or Framework.

For my usecase, we distribute a reasonably large number of independent frameworks, and it would be great to be able to document them fully with DocC. Many of these frameworks depend on other frameworks, and would naturally be distributed together. When writing documentation there's a lot of value in being able to link from a class in framework A directly to some extra information that might be included in framework B. This is particularly useful when conforming to protocols across different frameworks: the generated Conforms to section would be even better if it could link out to documentation for the associated protocols.

I can definitely see how there might be issues when resolving these links, particularly if a doccarchive is being hosted on the web. I guess at some level it would be necessary to define a location for the documentation of external frameworks? I imagine resolution might work differently between, say, the Xcode Documentation window and the web?

Apologies in advance if this is a capability already in swift-markdown or docc that I've missed!

8 Likes

Hi @nathan!

Thanks for posting this. You're correct; today Swift-DocC does not support linking to symbols defined in other frameworks.

We're currently tracking adding support with [SR-15431] Support DocC references to symbols defined in another module · Issue #208 · apple/swift-docc · GitHub. If you could add some of the details from your post here in that bug report so we can be sure to cover your use case, that would be really helpful!

4 Likes

FWIW, this is the biggest thing that prevents me transitioning my package documentation to DocC.

The ability to extend types from other modules (such as the standard library) with your own methods is a key feature of Swift. For example, swift-numerics extends the standard library’s floating-point types with elementary math functions.

That these extensions are entirely missing from documentation, and cannot even be referred to by other parts of the documentation, is such a significant regression that it outweighs all of the many benefits of moving to DocC.

I know that it’s being tracked; I’m only mentioning it to signal that for some packages, it’s a deal-breaker.

Edit: ah, I see. Linking and documentation are considered different features.

7 Likes