We've yet to see many practical use cases for linking to specific symbols "up" the documentation hierarchy (for example inferred from the target's source dependency hierarchy). A few examples have been brought up but we felt that there were better ways to write that documentation which didn't involve bidirectional links. For example:
-
The inner target that wants to point to an example implementation for conforming to a protocol.
Here the conforming type's documentation would repeat the protocol's documentation. It would likely be more helpful to the reader to include specific implementation examples as inline code blocks or link directly to the relevant source code of the conforming type, rather than its documentation. Because that wouldn't link to documentation, it would be a regular https link and not a symbol link in DocC.
-
A package's top-level documentation wants to point to a list of consumers.
This documentation is most likely to only link to the top-level pages of the consuming packages, not individual pages in their documentation. In this case, cloning and building the consuming packages documentation for a single top-level link may not be worth it compared to a regular https link.
-
Documentation about how to use an outer symbol and an inner symbol together.
If this documentation is a bit higher level and/or covers more than a single symbol in either target, that could be an indication that it's better suited for an article than as documentation for any specific symbol. That article could exist in:
- the outer target
- the inner target
- package-level documentation
An article in the inner target has the same problems with bidirectional links as a symbol in the inner target would. However, both the outer target and the package-level documentation are able to link to symbol in both targets. Either the outer target or the package-level documentation is also likely a better conceptual place for this documentation.
If a consumer of the package is able to import only the inner target, it's also a bit odd if that target has documentation about API that's not available to the consumer.
On the other hand, if this documentation is very specific to a symbol in either the outer target or the inner target, that could be an indication that it's better suited as documentation for that specific symbol, rather than an article.
If it's specific to the outer API, then the documentation can link to documentation for both targets. If, however, it's specific to the inner API, then it can't link to the outer API.
One key question to ask here is if a consumer can import only the inner target. If they can, then the documentation would probably be more helpful to them if it focused on how the consumer's own code needs to interact with the inner API, drawing from the outer API's implementation as code examples (the first example use case)
-
Packages with one or more example projects
Currently, the preferred way for packages with dedicated example projects to document those example projects is to write a single article that describe what that example project showcases, any specific configuration or setup needed to run it, and possibly describe some of its implementation. This article would use a
@PageKinddirective to change its style from an "article" to a "sample code page" and a@CallToActionbutton to give readers a prominent button to check out that example project.In this case the article is a part of the target's documentation so links to the target's pages are local. In this case there are no other pages specific to the example project to link to.
We can see a possible future use case for larger example projects that have many pages of documentation about the example itself, maybe even documentation about its individual symbols. However, we consider this use case to be slightly different from linking between other targets in a package because the example project is not "API" for the consumer to use. This has a couple of implications:
- It's would "pollute" the navigation hierarchy and features like Quick Navigation if symbols from the example project displayed alongside the API documentation.
- The example project is likely to link to many pages in the target/package documentation but the only page that has a reason to link to specific symbols in the example project's documentation is the example project's "sample code page" with the call-to-action.
This means that there are additional aspects about combined documentation—other than unidirectional links—that isn't a good for example projects.
We don't have any specific plans for large example projects with their own documentation hierarchies, but if we were to consider it in the future it's possible that we would treat it like it as a special case with multiple unique behaviors that don't apply to "general" combined documentation.