Warning: "Link in document summary will not be displayed." is inaccurate.

[AnthonyMDev]

Description

When including a link in the Abstract of a documentation file, I get a warning emitted:

Link in document summary will not be displayed.

However the link does appear in the summary both in the Xcode Documentation Navigator, and in my deployed documentation HTML website.

It seems like this is working just fine now, so should we remove the warning?

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

[d-ronnqvist]

IIRC the original issue was the links in abstracts didn't display in the task groups on other pages. For example, If A listed B in one of its topic groups and B had a link to C in its abstract, then when viewing the page for A the link to C wouldn't display. I retested that scenario now and it does work.

I know that when working with content outside of the documentation catalog—which is a niche feature that most developers don't interact with—the references encountered in the abstract are not encoded and decoded so they would get lost.

I think that it would make sense to limit this warning to only when DocumentationConverter.emitDigest is true. One of the digest files that DocC writes is list of all the pages that other systems can link to and that file would contain incomplete information (it would be missing the reference) if a page's abstract contained a link. That way the diagnostics is still emitted when it's relevant but wouldn't be emitted for most developers.

[AnthonyMDev]

I know that when working with content outside of the documentation catalog—which is a niche feature that most developers don't interact with.

Is this just referring to url links? I didn't know you could reference a symbol outside of the documentation catalog. Is there any documentation on this? I'm working with multiple targets, and would love for my docs to be able to link from one target's symbols to anothers.

the references encountered in the abstract are not encoded and decoded so they would get lost.

I'm all for limiting the warning to when emitDigest is true, but would it also be possible to eventually resolve this underlying issue, or is that a hard limitation of DocC?

[d-ronnqvist]

Is this just referring to url links? I didn't know you could reference a symbol outside of the documentation catalog. Is there any documentation on this? I'm working with multiple targets, and would love for my docs to be able to link from one target's symbols to anothers.

Swift-DocC has the core infrastructure and interfaces to support this but it doesn't come with and end-to-end solution so it's not covered as a user-facing feature. Interacting with this system will require some custom code by the developer and additional configuration to integrate it in their documentation workflow.

If you're curious, the implementation is well documented including some higher level descriptions like this one. It's primarily meant as a way to interact with other systems via a common data exchange format. The tests in OutOfProcessReferenceResolverTests utilize the system end-to-end using a small bash script as the custom implementation (bin/test-data-external-resolver). It would be possible to use this system to interact with other DocC content but even for someone who is deeply familiar with this code it's a fairly challenging task.

I'm all for limiting the warning to when emitDigest is true, but would it also be possible to eventually resolve this underlying issue, or is that a hard limitation of DocC?

The underlying issue can definitely be resolved but it's a fair bit of work.

The easy pieces would be to encode and decode the references from the abstract in LinkDestinationSummary. Where it gets complicated is in OutOfProcessReferenceResolver (or other custom implementations of ExternalReferenceResolver) which would need to pass the resolved references throughout the remained of the documentation build, since the original link from the external abstract is almost guaranteed to not be locally resolvable.

[Kyle-Ye]

Related issues: swiftlang/swift-book#1