This implements a change that @patshaughnessy suggested to me a couple of weeks ago; leveraging the markup's source information to avoid visiting a symbol's markup twice if that symbol's documentation is a mix of in-source comments and documentation extension file content.
Before this change, when a symbol had documentation content from both an in-source documentation comment and a documentation extension file, the context would visit the symbol's full markup twice passing different source URLs to the reference resolver which would filter out any diagnostics that didn't match the markup's source information.
Now, the reference resolver doesn't have a separate source property and instead relies solely on the source information from the markup. This means that a single pass is enough, no matter how many "doc chunks" the documentation node may have.
This also removes the need to filter out the duplicated diagnostics which have been a source of user facing bugs and also crashes (although the crashes should be resolved by #947 🤞).
Dependencies
None
Testing
This is a non-functional change. Everything should continue to work the same.
The relevant functionality to test for regression would be link resolution diagnostics (symbol links, documentation links, and image references) in in-source doc comments and documentation extension files. For example:
/// Some description of this class
///
/// Can link to ``doSomething()`` but not to ``NotFoundSymbol`` or <doc:NotFoundArticle>.
///
/// ![This image isn't found](some-not-found-image)
public class Something {
public func doSomething() {}
}
# ``Something``
Line 3 in the doc comment have two unresolvable links. Those should't appear here.
Here's two more unresolvable links to ``SomeOtherNotFoundSymbol`` and <doc:SomeOtherNotFoundArticle>.
Links to ``Something`` and ``doSomething()`` should resolve.
![This image isn't found](another-not-found-image)
or
/// Some description of my class
///
/// Can link to ``doSomething`` but not to ``NotFoundSymbol`` or <doc:NotFoundArticle>.
///
/// ![This image isn't found](other-not-found-image)
@interface MyClass : NSObject
- (void)doSomething;
@end
# ``MyClass``
A link to ``Something`` should work but not ``NotFoundSymbolName`` or <doc:NotFoundArticleName>.
![This image isn't found](some-other-not-found-image)
## Topics
- ``Something``
- ``SomethingNotFound``
Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
[x] Added tests
[x] Ran the ./bin/test script and it succeeded
[x] ~Updated documentation if necessary~ Not applicable
Bug/issue #, if applicable: rdar://129677496
Summary
This implements a change that @patshaughnessy suggested to me a couple of weeks ago; leveraging the markup's source information to avoid visiting a symbol's markup twice if that symbol's documentation is a mix of in-source comments and documentation extension file content.
Before this change, when a symbol had documentation content from both an in-source documentation comment and a documentation extension file, the context would visit the symbol's full markup twice passing different source URLs to the reference resolver which would filter out any diagnostics that didn't match the markup's source information.
Now, the reference resolver doesn't have a separate source property and instead relies solely on the source information from the markup. This means that a single pass is enough, no matter how many "doc chunks" the documentation node may have.
This also removes the need to filter out the duplicated diagnostics which have been a source of user facing bugs and also crashes (although the crashes should be resolved by #947 🤞).
Dependencies
None
Testing
This is a non-functional change. Everything should continue to work the same.
The relevant functionality to test for regression would be link resolution diagnostics (symbol links, documentation links, and image references) in in-source doc comments and documentation extension files. For example:
or
Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/test
script and it succeeded