comment_references doesn't recognize [this] when documenting a class member.

[srawlins]

Here's a repro:

class C {
  /// Returns [this].
  C get c => this;
}

comment_references complains. If this is the same issue as #57783, feel free to close.

[srawlins]

@pq you changed comment_references to always flag [this], along with [null], [true], and [false], for #57642. #57642 only calls out true and false, and I wonder if flagging [this] is too harsh.

@jcollins-g can you say offhand whether dartdoc resolves [this], in a doc comment on a class method or extension method, to the class?

[srawlins]

As an aside, there is a hope to document synthetic types like dynamic, void, Never, and maybe even values like null.

[bwilkerson]

It would seem odd to me for [this] to link to the class declaration because this doesn't refer to the class, it refers to an instance of the class. Also, it doesn't seem very helpful given that the class declaration is usually very close at hand or easy to navigate to from the declaration of the extension. And I'll note that this doesn't have navigation within code either.

If it did link to the class, then where should super link to?

[srawlins]

That's fair. I can write things like "this [DartType]" or "`this`" instead of "[this]", when writing a doc comment on a method for DartType.

[pq]

Hrmmm.

@pq you changed comment_references to always flag [this]

I can't quite remember but my thinking is I was striving for consistency w/ dartdoc so the warning could prevent you from comments that dartdoc wouldn't be able to generate nice links for. I'd be curious what @jcollins-g thinks.

[srawlins]

I'll close; no need to dig in further.

[jcollins-g]

I think [this] should be allowed as a comment reference in general; I'm actually adding support for it where applicable in the new dartdoc lookup system.

Rationale: Instances are not documented, so [this] referring to an instance of a type rather than the type/class itself is a distinction without a difference. [this] also allows you to refer to this class or any subclass, vs a specific class or type. This is useful in documentation when members are inherited -- you may wish to refer to the class the method shows up in vs a literal class.

[bwilkerson]

This is useful in documentation when members are inherited -- you may wish to refer to the class the method shows up in vs a literal class.

I don't think we can mimic that behavior in an IDE because members are not copied down into subclasses. The documentation will only ever appear in the class to which [this] would link.

Do we have a request for being able to link to the subclass to which the documentation was copied? If not I wonder whether we really want to introduce another incompatibility.

[jcollins-g]

To clarify, dartdoc supports [this] already, I just recently added it to the new lookup system to preserve the behavior.

[srawlins]

@bwilkerson I propose we re-close this. I don't think there is strong desire or capability to link [this], and I can drop support in dartdoc, in order to facilitate the migration to analyzer-resolution.

[bwilkerson]

I agree.