[SymbolGraphGen] Add filename and module name to symbols' doc comments #58857
Conversation
QuietMisdreavus
requested review from
d-ronnqvist,
franklinsch,
zixu-w and
daniel-grumberg
|
@swift-ci Please smoke test |
lib/SymbolGraphGen/Symbol.cpp
Outdated
| auto Loc = DocCommentProvidingDecl->getLoc(/*SerializedOK=*/true); | ||
| if (Loc.isValid()) { | ||
| auto FileName = DocCommentProvidingDecl->getASTContext().SourceMgr.getDisplayNameForLoc(Loc); | ||
| if (!FileName.empty()) { |
There was a problem hiding this comment.
Maybe this pattern could be refactored to avoid code duplication?
There was a problem hiding this comment.
I've pushed up an attempt to split out the file name collection and serialization so that serializeLocation can use the same code paths as serializeDocComment here. It was a bit awkward to work it around serializeLocation, but maybe i could re-duplicate the file-name collection but keep the serialization refactored like this. 🤷♀️
There was a problem hiding this comment.
The second option is what I had in mind (just deduplicating the code that is now in serializeFileURI). However the new version is kinda nice, I don't think it is awkward to read. Maybe the functions shouldn't be called getFileURI since they don't actually return URIs but rather pathnames.
There was a problem hiding this comment.
Good call! I've amended the commit to rename the functions.
|
@swift-ci Please smoke test |
QuietMisdreavus
force-pushed
the
QuietMisdreavus/comment-loc
branch
from
75d9acf to
ef15476
Compare
|
@swift-ci Please test |
|
I added a test to double-check that docs inherited from an external module (in this case, the standard library) correctly identifies the source module of the comment. @swift-ci Please smoke test |
Resolves rdar://81190369
Currently, doc comments in the symbol graph only include information about line/column numbers when referring to its location. However, if docs are inherited (and source information is available), these locations may point to a different file than the one for the symbol's declaration. In addition, the inherited doc comment might have been written with its original module in mind, for example by using Swift-DocC symbol links that point to other symbols in the module. These symbols may not be able to resolve in the inheriting module, which causes spurious errors when building documentation.
This PR adds two new sub-fields to the
docCommentfield:uriandmodule. Theurifield points to the file from which the doc comment was declared, and themodulefield indicates which module it's in. This can be used for more accurate diagnostics (even in docs are inherited within the same module) and to determine when a doc comment is inherited from a different module than the one being documented.