False positive in unintended_html_in_doc_comment lint

[natebosch]

The lint fires on references to generic classes in square braces.

/// [List<int>]

In dart doc this generates valid HTML that links to the List class. The lint should allow this (even if `List<int>` with backticks may be better style for these cases).

[lrhn]

This is tricky because [List<int>] is special DartDoc syntax, not CommonMark syntax.

The CommonMark interpretation is to treat the [ and ] literally, unless you have a

[List<int>]: linkTarget

declaration somewhere in the file. Then it is a shorthand link. (Which means parsing is not context free.)

In either case the <int> will be considered an HTML tag when rendered.

If DartDoc replaces remaining [List<int>]s by something else, then ... we probably need to figure out which criteria are used for that, and which approach is used to find the tags in the DartDoc code.
(Does it do Commonmark parsing first, then look for remaining [...]s which were not parsed as a link? if so, is the contents of [...] already markdown parsed too? Has it removed the unknown HTML tag <int> like it would remove <int> outside of a [...]? Is that why it works? Does [List<div>] work the same?)

Doesn't feel like a slam-dunk, but we probably can recognize \[[^`[\]]*\](?![([]) to ignore the contents of the [...]. It just won't find

Is [foo<upper>2</upper>] valid?

[foo<upper>2</upper>]: https://example.com

where you intended to write <sup> instead of <upper>.

[natebosch]

I found an example where this might be the best way to write it.

https://github.com/dart-lang/tools/blob/d563c38c7cfb03bbf5d1f9360b49c36ba45b97ef/pkgs/graphs/lib/src/topological_sort.dart#L38

Here its useful to link to the exception since it's novel, and it's useful to include the detail of the generic matching the generic on the method call. I can't find a way like prefer to phrase it where these aren't the same word.

[natebosch]

Closing in favor of #59516