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 todocc
. 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.