apple / swift-docc

Documentation compiler that produces rich API reference documentation and interactive tutorials for your Swift framework or package.
https://swift.org/documentation/docc
Apache License 2.0
1.14k stars 118 forks source link

Avoid visiting symbol markup twice when there's a documentation extension file #951

Closed d-ronnqvist closed 2 weeks ago

d-ronnqvist commented 2 weeks ago

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:

/// 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.

d-ronnqvist commented 2 weeks ago

@swift-ci please test

d-ronnqvist commented 2 weeks ago

@swift-ci please test