right now Biome relies on a markdown block directive @import(_:) to import modules for symbol-linking. this is useful for articles, but ideally it should not be needed for doccomments: they should just import the same set of modules their enclosing file imports.
would it be possible for SymbolGraphGen to emit the list of imported modules visible to a doccomment?
I'm not sure what information would be available inside SymbolGraphGen (i just haven't looked), but if that information is available, we could put a sort of visibleModules list on symbols which could be used for external link resolution. I'm not sure how Swift-DocC does it right now, but if there's a block directive for it, it might be possible to use information from the symbol graph as well? cc @ronnqvist @daniel-grumberg
I don't think this information is sufficient to solve the problem; it's incomplete for mixed-source frameworks and swift projects that use bridging headers. Is there a way to look this information up at a higher level, e.g. using SPM to get a dependency graph?
SPM-level information won’t help here, because the set of modules a particular target depends on is usually much larger than the set of modules imported by a particular file. to make every linked module visible would be casting far too wide a net, for the same reason why source files do not implicitly import every module their corresponding target is linked to.
references to entities from within doccomments should behave analogously to the way references to entities from within source code behave. so i think scraping import statements is perfectly appropriate here.
do you have an alternative to suggest, that does not require users to manually @import(_:) every module they want to reference, for each doccomment?
Are you talking about documenting multiple targets/frameworks together?
yes
In which case, you should take a look at David's recent proposal about implementing multi-target documentation archives for Swift-DocC. Using this sort of approach you wouldn't need to do manual imports of anything and links that would resolve in the other archives would be automatically resolved. Not sure this is feasible within biome's context but that is the approach Swift-DocC is hopefully going for.
yes i’ve seen that proposal and have commented on it. it enables visibility for all modules in a documentation archive, which is different from the goal here, which is to limit module visibility to only those modules that were imported in the original source file.
symbollinking already struggles with overloading (due to case-folding), adding name collision precedence rules that are different from the ones used by the compiler when compiling source code increases the cognitive burden further, and feels like a step backwards to me.