Expand analyzer's resolution of Dartdoc comment references

[srawlins]

Currently the set of allowed comment references is very very small. Something like:

• simple identifier (one word)
• prefixed identifier (foo.bar), for an import prefix and library-level element pair, for a named constructor, and for a static method

We'll expand the set to include:

• static method or constructor on a prefixed library element (foo.bar.baz)
• type literal with type arguments (foo<...>)
• constructor tear-offs with type arguments (foo.bar<...>), including constructor on a prefixed library-level element
• function tear-offs with type arguments (foo<...>) for top-level functions and static methods

All identifiers, including type arguments, should be hoverable and jumpable. Dartdoc's comment reference resolution is already separate from analyzer's and supports more expressions; it can be separately updated to match (or use) analyzer's resolution more closely.

This will be accomplished with a new interface, CommentReferableExpression, and a new member on CommentReference, called expression.

Steps to get there:

1. Add new node; update Identifier, PropertyAccess, TypeLiteral, ConstructorReference, FunctionReference to implement new node; add CommentReferableExpression get expression to CommentReference; deprecate CommentReference.newKeyword and CommentReference.identifier; change implementation of CommentReference.identifier to return expression as Identifier.
2. Publish and update clients to use expression.
3. Update resolution to resolve more comment text to resolve to CommentReferences; remove CommentReference.newKeyword and CommentReference.identifier.

[srawlins]

CC @bwilkerson for any comments.

[srawlins]

CC @eernstg who cited the spec in another recent issue about comment reference resolution.

[eernstg]

Right, that would be #56259 (comment).

[FMorschel]

I was thinking about this, it would be good to support

/// Works with a [List<T>] internally
void foo<T>() {
  var list = <T>[];
}

[bwilkerson]

Are there examples of places where users are using type annotations as references (as opposed to simple type names)? I don't want to add features that nobody wants to use.

If we were to add support for type annotations then we might need to support all type annotations, not just those involving a type name and a list of type arguments. In particular, we'd need to consider function types and record types.

[FMorschel]

I think I've seen (in Flutter SDK IIRC) a reference to [List<String>] before (probably got removed because it doesn't work) but never type parameters.

Are there examples of places where users are using type annotations as references (as opposed to simple type names)?

I'm unsure. Probably not, but that may be because of this and #60417. With type parameters having little to no use on docs today, this answer may be biased since people may notice that it doesn't work as expected and remove this part from the docs or replace it with something else.

[bwilkerson]

Yes, the lack of support might be biasing users. I could hope that if users want to use type annotations in comment references and then notice that it doesn't work, that they'd open a request for it, though I know that that won't always be the case. Even so, we don't have unlimited resources so we can't add support for everything that someone might want.

[lrhn]

Are there examples of places where users are using type annotations as references

I've seen [List<int>], or similarly instantiated types, plenty of times.
I think it also accidentally "works" because DartDoc erases the invalid HTML tag <int>. Won't work so well for [List<Div>].

[srawlins]

Yeah, grepping the Flutter codebase as one example, there are 16 cases of ///.* [List<. I imagine Future<, Map<, etc would be similarly common.

[FMorschel]

I've just noticed at dart-lang/test#2481 (comment) that this is displayed the same as the comment:

I think I've seen some references to it like that. I've not yet looked at the resulting HTML to see what happens, but I was wondering if this is just a "non-"reference visual or if this is also not supported.

[bwilkerson]

I don't believe that we support the use of this as a comment reference. There is no explicit declaration of this, so it isn't clear where the user would expect that to link to.

[srawlins]

Yeah we made an explicit decision to stop supporting [this] in dartdoc, as analyzer does not support it, and it makes sense to not support it.