Make resolution of comment references homogeneous

[a14n]

Comment references are currently handled in different ways in:

• code navigation
• lint comment_references
• dartdoc

This should be fixed at the analyzer level to have consistency accross tools (linter, dartdoc, code navigation...). After that tools should be updated to use an analyzer API to resolve comment references.

Related issues:

• Loads of unresolved doc references flutter/flutter#31931
• handle dartdoc references to non-imported symbols (was: dartdoc-specific imports) dartdoc#1153
• comment_references lint doesn't support dartdoc's idea of "in scope" linter#1142

[a14n]

/cc @bwilkerson @jcollins-g @pq

[srawlins]

Hi @a14n can you note if you have any specific needs that are affected by this shortcoming? Just because some inconsistencies are going to be much harder to implement than others:

• @tool from flutter, @macro from flutter
• references to non-imported elements

[a14n]

TBH I don't exactly remember everything. But the issue was raised after inconsistencies where the lint comment_references was triggered though dartdoc was ok and code navigation was working (or not - I don't remember).

[srawlins]

+1; that lint can generate a lot of false positives and I have a plan to fix it :)

[srawlins]

These are more aligned than they used to be. I've made some fixes to the comment reference parsing, and there is a remaining problem, documented in a separate ticket. The remaining work is all in the dartdoc side. You can track with dart-lang/dartdoc#3798.