`unintended_html_in_doc_comment` - add to recommended set

[kevmoo]

Describe the rule you'd like to see added and to what rule set
https://dart.dev/tools/linter-rules/unintended_html_in_doc_comment

Additional context
It's almost ALWAYS helpful. Trouble imagining false negatives.

Need to wait until Dart 3.5 is stable, though.

[lrhn]

Does it have exceptions? (Fx <sub> and <sup> have no markdown equivalent in Commonmark or GitHub markdown, and HTML is valid inside Commonmark).

The name is "unintended...". It's there intended uses? If so, what are they?

Is there a way to opt out?

Can I do

/// If _X_<sub>2</sub> 

If not, can I do <!-- ignore:... --> to ignore for this or the next line, or will I have to ignore_for_file?

[devoncarew]

cc @kallentu and @srawlins who may have the most context with this lint

[srawlins]

Does it have exceptions?

<sub> and <sup> are in the allowlist.

The name is "unintended...". It's there intended uses? If so, what are they?

Just the allowlist, I suppose.

Is there a way to opt out?

Nothing beyond the standard recommended way (with // ignore or // ignore_for_file comments).

Can I do /// If _X_<sub>2</sub>

Yes.

[lrhn]

Ack. The documentation should probably at least mention that there is an allowlist, preferably include the list.

May also want to say why

/// <http://foo.bar.baz>

is considered "good" and that it's not parsed as HTML, counter to what the first sentence says.

You are allowed to use custom tags in Commonmark, but I don't see any use for that in dartdoc, so there is probably no need for ignores.
(If a need shows up, we may consider allowing ignores inside <!-- --> comments, unless we already allow interleaving // comments inside /// doc blocks.)

👍 if the docs are updated.

[devoncarew]

From an off-line discussion:

• google3 data indicates most lints are triggering on real issues
• between now and the next publish, it would be nice to get some data on ext. impact (i.e., any false positives?)
• this does prevent real issues - preventing dartdoc from generating malformed or unintended html

resolution: OK to include in core w/ the next major release

[lrhn]

OK to include in core w/ the next major release

The lint is still listed as experimental. We'll want to graduate it.
Also, the documentation/specification must be updated before we do that. It's misleading as written.

(I treat the documentation of lints as their specification, since there is no other place to find a specification. The documentation should be good enough to be used as a specification.)

[pq]

/fyi @kallentu @srawlins @parlough

[devoncarew]

The lint is still listed as experimental. We'll want to graduate it. ...

Thanks, make sense. I opened dart-lang/sdk#59501 for the doc work on the lint.

[kallentu]

Oh yeah, thanks for looking at it @lrhn.
I noticed the first line of the documentation is just completely wrong haha. We didn't catch that last review.

I'll update it and send it out.

[kallentu]

Docs should be updated now.
We can move forward with including it in the core set.

[devoncarew]

We're trying on the lint in package:dart_flutter_team_lints; it looks like there are some false positives - relatively infrequent html entites that are actually used in dartdoc comments - things we don't want escaped. Srujan hit this in package:web and opened dart-lang/sdk#56450 to track.