Symbol link priorities and links to extensions
There are a number of subtleties to how symbol links work in DocC.
That's mostly true but the missing piece is that DocC resolves all references relative to the page where the link occurs. For example, in this hypothetical code:
// 1: the module is named "Something"
class TopLevelSymbol {
class Something { // 2: the first nested symbol
class NestedOne {
class NestedTwo {
class Something { // 3: the deeply nested symbol
...
}
}
}
}
}
class DifferentSymbol {
...
}
The link ``Something`` from the documentation for NestedOne would resolve to the outer nested symbol (2) since that's the container scope but the same link from the NestedTwo documentation would resolve to the deeply nested symbol (3) since that's the descendant.
Similarly, the ``Something`` link from the documentation for TopLevelSymbol would resolve to its descendant symbol (2). Only from the documentation for DifferentSymbol would the ``Something`` link resolve to the module (1).
A leading slash would provide the ability to express an intentional reference to the module in cases where relative descendant or container symbols would otherwise be preferred.
If instead the hypothetical code had a top level "Something" symbol like this:
// 1: the module is named "Something"
class Something { // 2: now a top-level symbol
class NestedOne {
class NestedTwo {
class Something { // 3: a deeply nested symbol
...
}
}
}
}
class DifferentSymbol {
...
}
then a ``Something/Something`` link could either be interpreted as "<module> / <top-level>", "<top-level> / <member-of-top-level>", or "<nested> / <member-of-nested>" in all of the possible scopes. Only the first interpretation would resolve successfully. This means that link resolver implementations need to either back track, branch, or look ahead depending on what their overall link resolution strategy is.
This also becomes relevant for links to extensions.
This is a very good point and I see that my phrasing was a big the ambiguous when I said (emphasis added)
I propose that the existing symbol link syntax be extended with a leading slash for links to symbols in other targets.
What I should have said is
[...] a leading slash for links to symbols in documentation archives passed as dependencies.
Since extensions are content for the extending module and as passed as the main input to DocC they would be resolved as local symbol links and wouldn't need a leading slash. It would still be optional and DocC would try to resolve the link locally before checking external resolvers.
If I understand this correctly it means that local content is prioritized over external content. If so, that's how I imagine it would work as well. Even with an optional leading slash, DocC would try to resolve links locally before resolving them as external references. Because of the way that links are always resolved relative to other pages I feel that it's still useful to prefix a local link to with a slash to treat it as an "absolute1" symbol link instead of resolving it relative to the current page.
1. The term "absolute" symbol links can have many meanings. The resolved path to the symbol page in the documentation archive will have an added initial "documentation" path component. This isn't necessary to include when writing the link in content since symbols links can't resolve to tutorials but it is supported to write a symbol link like ``/documentation/SomeTarget/Something`` .
This would mean that if a local extension matched ``/OtherTarget/Something`` then DocC wouldn't attempt to resolve "Something" in the external "OtherTarget" documentation archive dependency.
This is what I propose that we change. I view it as a benefit to the developer or contributor of the documentation to be able to read or write a symbol link without a leading slash and know that it refers to some local symbol or some local extension.