Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
Mordil opened this issue Nov 3, 2021 · 21 comments
Open
Labels
new feature New features or new functionality

Comments

@Mordil
Copy link

Mordil commented Nov 3, 2021

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
Copy link
Author

Mordil commented Nov 3, 2021

This has also been filed in Feedback Assistant with FB9410972

@swift-ci
Copy link

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
Copy link

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
Copy link

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
Copy link

slashmo commented Jan 24, 2022

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

@swift-ci
Copy link

swift-ci commented Feb 6, 2022

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.

@swift-ci swift-ci transferred this issue from apple/swift-issues Apr 25, 2022
@shahmishal shahmishal transferred this issue from apple/swift May 3, 2022
@maweefeng
Copy link

any news for this ?

@flockoffiles
Copy link

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

@spnkr
Copy link

spnkr commented Jan 11, 2023

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

@Vitalii-Gozhenko
Copy link

+1 for this feature. Sometimes it is incredible usable

@proj-sashido
Copy link

+1 for this feature!

@Saafo
Copy link
Contributor

Saafo commented Mar 3, 2023

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

@gposcidonio
Copy link

Big +1 gang.

@SomeRandomiOSDev
Copy link

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

@extremereality2
Copy link

+1 for this feature

@ricocrescenzio95
Copy link

+1 for this guyssss

@RemiBardon
Copy link

Any news regarding implementation?

@KirillLezhninRMR
Copy link

+1 for this feature

@d-ronnqvist
Copy link
Contributor

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
Copy link
Contributor

I want to emphasize that it's very early but we are making some progress on this front with #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
Copy link

joshuapoq commented Mar 7, 2024

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
new feature New features or new functionality
Projects
None yet
Development

No branches or pull requests