Start using docImport resolution when resolving references

[srawlins]

Currently dartdoc uses a two-step strategy to resolve doc comment references:

First, for each reference in square brackets, dartdoc asks analyzer's Scope.lookup API for what a reference should resolve to. (Note: that API does not support resolution that includes the "doc import" scope which is introduced by @docImport.) Second, if Scope.lookup could not resolve the reference, dartdoc uses it's own lookup system which searches outward for identifiers (the "universal scope" system).

In this change, we introduce a third step: between the existing two steps, we check the ModelNode.commentData references. These references do take the "doc import" scope into account. So here is the new process:

1. Check analyzer's Scope.lookup API. If that returns null,
2. Check analyzer's earlier resolution, which includes the "doc import" scope. If that returns null,
3. Resolve the reference with the "universal scope" system.

This should not change any existing successful resolutions into different, unintended resolutions. Introducing the second step should only start resolving references that can be resolved specifically because of an introduced @docImport.

The only secondary change here which is needed to facilitate the @docImport change is to declare that extension members are "contained" by their enclosing extension. I don't know why this wasn't the case before. It doesn't seem intentional, as the tests continue to pass. I think it was an oversight, or a misunderstanding of extension members.

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Contributions to our repos should follow the Dart style guide and use dart format.
• Most changes should add an entry to the changelog and may need to rev the pubspec package version.
• Changes to packages require corresponding tests.

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

[srawlins]

CC @dart-lang/analyzer-team

[scheglov]

Clever, maybe too much :-P
Match a pattern, and then check a condition that does not use the pattern.

Ideally, should be a separate if enclosing the pattern matching one, but one liner is tempting :-)

[srawlins]

Yeah I definitely thought this was a little weird :P Specifically because it seems like the when resultElement == null should be first. But we cannot write if (resultElement == null && this case ModelElement(:var modelNode?)). I can split it up in a follow-up.