Combined documentation of multiple targets

[taylorswift]

@ronnqvist

I think we may have different ideas of how to link to specific versions of documentation and possibly about the uses cases for doing so. I'll explain my thinking below. Please add yours as well.

In my view, DocC always works with the "local" version of a target and its dependencies. This means that when a developer writes a link to a dependencies' symbol they always write /TargetName/SymbolName (without any version information). In the locally built documentation the link points to the locally built documentation.

aha. Biome (since v0.2) does not really have a concept of a “local” target or a dependency root. Biome has a concept called culture which is relative, orthogonal to module namespace, and is defined for every module in its modulegraph.

culture determines the “rights” a particular symbol has within a particular context, how much the compiler “trusts” relationships emanating from that symbol, and how the compiler breaks ties when edge cases occur.

culture is basically a generalization of “locality”, and because it is relative, it means Biome doesn’t have to globally privilege any symbol or group of symbols.

for a more concrete example of this in action, if you go to the docs for swift-json, you’ll see that they connect to the docs for swift-grammar. however it would be incorrect to say that swiftinit hosts documentation “for swift-json that includes docs for swift-grammar”, just as it would be incorrect to say that swiftinit hosts documentation “for swift-grammar that includes docs for swift-json”. the same is true for swift-nio and the other packages on the site.

@ronnqvist

I could also see /TargetName-version or /TargetName@version working to disambiguate between the different versions of a target's documentation but that syntax is for a separate later discussion.

i considered these spellings but i rejected /TargetName-version because it does not generalize well to branch references (TargetName-master looks like a package name), and /TargetName@version because i did not want @ signs showing up in URLs.

versions are also logically a package-level concept, so it makes more sense for it to show up on the left-hand side of the module name.

@ronnqvist

Collisions between symbols and targets shouldn't happen with this syntax. For example if "MyTarget" had a "Something" dependency and a "Something" symbol then /Something would refer to the dependency and Something would refer to the symbol.

based on reading How to properly reference a type and module with the same name? , i assumed ``Something`` would refer to the module, and ``Something/Something`` would refer to the the symbol. if this is true, then ``/Something`` would not provide any additional expressive power.

i always found this strange, but i implemented the lookup algorithm in Biome this way for consistency with DocC.