Warning on comment references for Dart keywords

[FMorschel]

From @bwilkerson's #47444 (comment):

There is no explicit declaration of this, so it isn't clear where the user would expect that to link to.

From @srawlins' #47444 (comment):

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

Maybe we could think of other cases like this, but at least for this, super, false, true, null, etc, we could probably create a warning to suggest the user to stop using [] and to prefer backsticks.

[bwilkerson]

If dartdoc isn't going to support these then it makes sense for us to let users know. We already have INVALID_COMMENT_REFERENCE to flag other kinds of invalid references. We should think about reusing this same warning (possibly with a different code if the message should be different) to report these cases.

[srawlins]

Maybe we could think of other cases like this, but at least for this, super, false, true, null, etc, we could probably create a warning to suggest the user to stop using [] and to prefer backticks.

I think these are all reported by the comment_references lint rule. See the tests: https://github.com/dart-lang/sdk/blob/main/pkg/linter/test/rules/comment_references_test.dart#L249

[FMorschel]

They are reported as if the keywords don't exist in scope. I'd prefer the INVALID_COMMENT_REFERENCE warning. They could only be triggered when that lint is on, but for keywords, I don't see any problem in having that all the time. Of course, usable (we can name things with them) keywords like async and such, should not trigger.

[srawlins]

Ah I see. I think we can just add an additional LintCode then to the comment_references AnalysisRule. The LintCode is what controls the messaging.

[bwilkerson]

I think these are all reported by the comment_references lint rule.

Interesting. It appears that almost nobody has that lint enabled. I don't know whether that's because nobody cares about this or whether nobody knows the lint exists. If it's the former then we don't really need to do anything about this. If it's the latter then we should consider whether a warning would be more appropriate.

[srawlins]

I'd love to convert it to a warning. But I'm pretty sure there will always be false positives until we can use a real markdown parser in the rule. I don't have any examples offhand. But a real markdown parser can handle escaped characters like [foo\]. There are a lot of weird corner cases when parsing markdown links. And then tracking inline code, with backticks. And then escaped backticks...

[FMorschel]

I only got the knowledge of this lint recently, so I suspect the latter. I would even argue that it should probably be on effective Dart now that we have doc imports, but I guess we could wait until the fixes produce the right import kind at least.

• Make comment_references fixes add doc imports instead of normal imports #59759