[SR-15431] Support DocC references to symbols defined in another module

[Mordil]

Previous ID	SR-15431
Radar	rdar://79049385
Original Reporter	@Mordil
Type	New Feature

Additional Detail from JIRA

| | | |------------------|-----------------| |Votes | 19 | |Component/s | Swift-DocC | |Labels | New Feature | |Assignee | None | |Priority | Medium | md5: c3c52c8ed342d1b0fea2c443bcf8f543

Issue Description:

As a database driver author, I rely heavily on SwiftNIO for the architecture of my driver, and users of my driver should be familiar with many of the concepts and types defined by SwiftNIO that I also expose.

When I write symbol documentation or articles, I would like the ability to reference those types, to enrich the exploration of documentation with Xcode.

The syntax I would find the least surprising is having to prepend the module's name at the start, such as ``SlothCreator/Habitat``

[Mordil]

This has also been filed in Feedback Assistant with FB9410972

[swift-ci]

Comment by Ellen Shapiro (JIRA)

This would also be super-helpful for us at Apollo GraphQL - we have small sub-libraries for things like handling a SQLite persistence layer and WebSockets that we would love to be able to link to our main lib as well.

[swift-ci]

Comment by Alexey Ivashko (JIRA)

+1 on this. I distribute internal frameworks as one package but as several different libraries in order to use only the code I needed for my targets. Referencing another module from my own would be such a pleasure, because I have several "protocol" only frameworks that have "concrete" frameworks implementations. And also, sometimes I would like to reference existing system framework documentation in order to guide user to fully learn about my api

[swift-ci]

Comment by Martin Heinrich (JIRA)

+1 for this request
Work is split into multiple modules and documentation needs to mention types that are referenced or extended. This is the case for modules under ones control, but even more for third party modules used or operating system frameworks.

[slashmo]

+1 on this as well. We'd also need to cross-reference across targets in the Distributed Tracing repos.

[swift-ci]

Comment by Akos Polster (JIRA)

+1 on this. We are distributing an SDK as a set of frameworks. Documenting them as a single unit would be great.

[maweefeng]

any news for this ?

[flockoffiles]

I would also be very much interested in having this support implemented.

[spnkr]

👍 . This is the only thing preventing me from using DocC for my documentation.

[Vitalii-Gozhenko]

+1 for this feature. Sometimes it is incredible usable

[proj-sashido]

+1 for this feature!

[Saafo]

+1 for this feature, it's very important to me!

[gmedori]

Big +1 gang.

[SomeRandomiOSDev]

+2 if allowed, otherwise +1. Been looking for a way to do this for quite some time

[extremereality2]

+1 for this feature

[ricocrescenzio95]

+1 for this guyssss

[RemiBardon]

Any news regarding implementation?

[KirillLezhninRMR]

+1 for this feature

[d-ronnqvist]

This feature is very important to us and to DocC but because of how central it is to the broader support for combined documentation for multiple modules, it needs to be thoroughly thought through so that there is a good path forward for future directions and so that we're not designing ourselves into a corner further down the line.

I find the thread of an individual issue to be both too broad and too narrow for the various discussions around a feature like this. The Swift Forums is a better place for that. That's where we've gathered inputs for use cases and discussed a proposed high level design for this. That design remains largely unchanged although some initial work have revealed a few areas that require further consideration to ensure that we have enough flexibility going forward without needing to design absolutely everything up front.

I should follow up in the Swift Forums with additional details about the plan.

I'll also think about ways, for example keywords, to indicate what issues and pull requests relate to multi-module documentation for those developers who want to follow along in the repo or who want to contribute.

[d-ronnqvist]

I want to emphasize that it's very early but we are making some progress on this front with https://github.com/apple/swift-docc/pull/710.

Even when that PR is merged, the overall user experience will be incomplete until we also support combining documentation from multiple targets into a unified archive.

[joshuapoq]

Very excited to come across this! Have been finding it frustrating that most guides or posts specify adding DocC to a 'framework or package' or using the 'package name', mixing terminology making it harder to figure out how to add DocC to a Swift Package of many products.

Based on that PR I guess right now we can only use command line to generate docs with cross-product links using the experimental parameter? And we'd need to specify each dependency for each target so there's no practical way to enable this within Xcode at the moment?

[daltonclaybrook]

Tomorrow marks one year since the last update on this. Has there been any new progress you can speak to @d-ronnqvist?

[d-ronnqvist]

Yes. I made this post in the Swift Forums a few weeks ago with an announcement that you can try out an early, and still experimental, version of this.

I'm not quite sure when it would be appropriate to close this issue. With what's possible in the 6.0 release you can link to symbols in other modules if you pass an experimental feature flag.