[Pitch] Enable automatic "mentioned in" links by default

[ronnqvist (David Rönnqvist)]

Hello Swift community,

Swift DocC 6.0 added an experimental "mentioned in" feature that automatically creates links from mentioned symbols to the articles that mention those symbols in text.

This helps the reader find long-form conceptual content that put a specific API in context or that describe how to accomplish some task using that API.

For example; the documentation for the /Swift/Result type uses this feature to automatically display links to the "Preserving the Results of a Throwing Expression" and "Writing Failable Asynchronous APIs" articles, just below its abstract and declaration.

This complements the documentation hierarchy in general—which a reader typically descends to find relevant content—by introducing a means to navigate up the documentation hierarchy to find specific content that's relevant to the symbol that the reader is currently learning about.

Ashley and I feel that this feature has been a useful addition and propose that Swift DocC 6.2 both:

• Remove its experimental status.
• Enable it by default.

This DocC PR makes both these changes and adds a brief description of this feature to the DocC documentation:

When you link to a symbol from an article's content, DocC automatically creates a "mentioned in" link from mentioned symbol's page to the article that mentioned the symbol. These "mentioned in" links helps the reader find conceptual content that put a specific symbol in context or that describe how to accomplish some task using that symbol.

DocC only creates "mentioned in" links when an article links to a symbol and only when that link appears in the article's content. Links in topic groups—that organize your documentation into a hierarchy of topics and subtopics—doesn't produce "mentioned in" links. For more information about topic groups, see Adding Structure to Your Documentation Pages.

Earlier Versions:
Before Swift-DocC 6.2, automatic "mentioned in" links require that you pass the --enable-experimental-mentioned-in command line flag to docc. This flag is available as of Swift-DocC 6.0.

If you want to try this in your documentation today you can pass the --enable-experimental-mentioned-in flag to Swift DocC 6.0 (which comes with Xcode 16.0) or later.

If, as proposed, we enable this feature by default you no longer need to pass a flag to enable it but you will be able to pass --disable-mentioned-in to Swift 6.2 or later to opt out of this behavior. The --enable-experimental-mentioned-in would continue to be supported (as a no-op) in Swift-DocC 6.2 but will be removed after that.

[jack (Jack Lawrence)]

This is really compelling—I can also see this data proving useful for other areas like search or new tools for documentation discovery.

Are there any heuristics we could use to decide whether to include a link in the mentioned-in list, or limits on the length of the list? What about sort order, could/should we sort by number of mentions or hierarchical proximity?

With only a module-wide feature switch, do you think some projects will have to disable the feature wholesale to address corner cases even when it's otherwise largely useful? In your experience with the feature, have you found any pathological scenarios like core fundamental types linked from every article, e.g. UIView in UIKit?

Finally, how do you see this relating to the see also section? Should they be combined? Are there scenarios where the mentioned-in section will duplicate links also in the see also section?

[grynspan (Jonathan Grynspan)]

Seems reasonable to me.

[ronnqvist (David Rönnqvist)]

@jack

Are there any heuristics we could use to decide whether to include a link in the mentioned-in list, or limits on the length of the list? What about sort order, could/should we sort by number of mentions or hierarchical proximity?

The current heuristic counts all symbol links in articles' abstract sections and discussion sections (including subsections) and weights links in the abstract higher than links in the discussion. On the symbol page, the mentioned in links are order based on these weighted counts. We consider these specifics to be an implementation detail that could change from release to release as we tweak the heuristic.

@jack

With only a module-wide feature switch, do you think some projects will have to disable the feature wholesale to address corner cases even when it's otherwise largely useful? In your experience with the feature, have you found any pathological scenarios like core fundamental types linked from every article, e.g. UIView in UIKit?

We have yet to encounter any projects that would want to disable this. In projects with some frequently references core type, that type tends to not be linked to from articles more than a handful times. For example; UIKit/UIView has 5 mentioned in links, UIKit/UIViewController has 4, SwiftUI/View has 5, RealityKit/Entity has 5, Combine/Subscriber has 4, etc.

DocC currently limits the number of items in an automatic See Also section to 15 (configurable via an environmental variable). There's not currently any corresponding limit for links in Mentioned In sections but we could add one (and make it similarly configurable) if there's a need for it.

@jack

Finally, how do you see this relating to the see also section? Should they be combined? Are there scenarios where the mentioned-in section will duplicate links also in the see also section?

I see them as complimentary. The See Also section helps the reader find other pages in the same subtopic in the documentation hierarchy whereas the Mentioned In section helps the reader find higher level conceptual content—regardless of its location in the documentation hierarchy—that put the current page in context.

For example the UIKit/UIViewController/viewDidAppear(_:) page lists viewWillAppear(_:), viewWillDisappear(_:), viewDidDisappear(_:), isBeingPresented, isBeingDismissed , etc. in its See Also sections because all those pages are organized into the "Responding to view-related events" Topics group on the UIViewController page. This helps the reader find other related symbols that are all about responding to view-related events.

DocC has two different reasons why it won't include those links in the Mentioned In section:

• Those links are in a Topics group.
• Those links are from a symbol to another symbol.

Instead, the links in the Mentioned In section for the viewDidAppear(_:) page are for these two articles which describe tasks when the reader might implement viewDidAppear(_:) and provide higher level conceptual information about the order that these (and other) methods are called when the developer presents a view controller onscreen:

• "Positioning content relative to the safe area"
• "Displaying and managing views with a view controller"

Both the See Also links and the Mentioned In links are valuable in their own way.

We see the Mentioned In links as something that could be relevant to reader before they read the details of the current API—so that section is displayed early on the page—and the See Also links as something that could be relevant to the reader after they've read about the current API—so that section is displayed late on the page.

It is possible that a link would appear in both these sections if an article that talk about a specific API is organized into the same subtopic as that API on their common container page. We could consider removing that link from the See Also section in this case but I personally don't feel like including that link in both sections negatively impact the reader, so I think I'd prefer to keep the link in both sections to give the reader a second reminder of that link towards the bottom of the page.