Analyzer cannot resolve instance reference on type variable, in a doc comment.

[srawlins]

The analyzer's "doc comment scope" is unable to resolve an instance getter reference on a type variable:

class C<T extends List> {
  /// Try [T.first].
  /// Try [List.first].
  void f() {}
}

List.first resolves properly, because we allow instance access as if it were static, on a type. T.first does not resolve, even though there is a first property on the bound. Seems like this should be allowed.

Came across this in DevTools code, and it seems reasonable.

[FMorschel]

I can take a look at this if you want me to 😁

[srawlins]

@bwilkerson might be interested to consider whether we should fix this. I myself realized that it is perfectly reasonably to just write out the instance member on the bound (write List.first instead of T.first). A user still might want to write T.first over List.first, just in terms of the text of the comment. Maybe they want "Assuming [T.first] doesn't throw." It makes sense there to refer to the implementation of List.first. But... maybe then, since you're not referring to the List.first implementation, it should not be in square brackets, linking to List.first. 🤷

If Brian looks at this, there is a 90% chance that he will think of something I haven't (other consequences, other reasons) 😁 .

[bwilkerson]

While I appreciate the flattery, I don't know that I have much to add.

I don't know how often this style is used, but we do have an existence proof. I mention that because if it's rarely used then it might be better, from a maintence perspective, to not support it.

From a purely theoretic perspective, it seems reasonable to be able to use a type parameter to reference a member as long as the type parameter has a bound that defines the member. We should flag cases where the bound doesn't define the member, but other than that I can't think of any issues, subtle or otherwise.

We probably shouldn't, however, allow references to static members of the bound. I think that would be confusing.

Just out of curiosity, do we handle typedefs?

[FMorschel]

Fully agree.

No, we don't handle typedefs but for them I'd say that static members could be allowed.

Static members for type parameters should not show up because we can't enforce all sub classes have them (at least currently).

[FMorschel]

One more point would be how to display that on dart doc pages but I guess it would get turned into the bound type, right?

[srawlins]

We do not support referencing members on typedefs. But this has been strongly requested for Flutter's SDK docs by @goderbauer here. For the purposes of incrementally renaming classes.

[bwilkerson]

... I guess it would get turned into the bound type, right?

I would assume that we'd want to display the text as it appears in the reference. It might make sense to link it to the bound, but it might be too magical. I don't have a strong opinion here yet.

For the purposes of incrementally renaming classes.

That makes sense.

[FMorschel]

I would assume that we'd want to display the text as it appears in the reference

Maybe something like T.first could show up as List.first (T.first) (or swapped) or something, and make this section as a whole be a link rather than only List.first.