unintended_html_in_doc_comment

Use of angle brackets in a doc comment is treated as HTML by Markdown.

DON'T use angle-bracketed text, <…>, in a doc comment unless you want to write an HTML tag or link.

Markdown allows HTML tags as part of the Markdown code, so you can write, for example, T<sub>1</sub>. Markdown does not restrict the allowed tags, it just includes the tags verbatim in the output.

Dartdoc only allows some known and valid HTML tags, and will omit any disallowed HTML tag from the output. See the list of allowed tags and directives below. Your doc comment should not contain any HTML tags that are not on this list.

Markdown also allows you to write an "auto-link" to an URL as for example <https://example.com/page.html>, delimited only by <...>. Such a link is allowed by Dartdoc as well. A <...> delimited text is an auto-link if it is a valid absolute URL, starting with a scheme of at least two characters followed by a colon, like <mailto:mr_example@example.com>.

Any other other occurrence of <word...> or </word...> is likely a mistake and this lint will warn about it. If something looks like an HTML tag, meaning it starts with < or </ and then a letter, and it has a later matching >, then it's considered an invalid HTML tag unless it is an auto-link, or it starts with an allowed HTML tag.

Such a mistake can, for example, happen if writing Dart code with type arguments outside of a code span, for example The type List<int> is ..., where <int> looks like an HTML tag. Missing the end quote of a code span can have the same effect: The type `List<int> is ... will also treat <int> as an HTML tag.

Allows the following HTML directives: HTML comments, <!-- text -->, processing instructions, <?...?>, CDATA-sections, and <[CDATA...]>. Allows DartDoc links like [List<int>] which are not after a ] or before a [ or (, and allows the following recognized HTML tags: a, abbr, address, area, article, aside, audio, b, bdi, bdo, blockquote, br, button, canvas, caption, cite, code, col, colgroup, data, datalist, dd, del, dfn, div, dl, dt, em, fieldset, figcaption, figure, footer, form, h1, h2, h3, h4, h5, h6, header, hr, i, iframe, img, input, ins, kbd, keygen, label, legend, li, link, main, map, mark, meta, meter, nav, noscript, object, ol, optgroup, option, output, p, param, pre, progress, q, s, samp, script, section, select, small, source, span, strong, style, sub, sup, table, tbody, td, template, textarea, tfoot, th, thead, time, title, tr, track, u, ul, var, video and wbr.

BAD:

/// The type List<int>.
/// <assignment> -> <variable> = <expression>

GOOD:

/// The type `List<int>`.
/// The type [List<int>]
/// `<assignment> -> <variable> = <expression>`
/// \<assignment\> -> \<variable\> = \<expression\>`
/// <https://example.com/example>

To enable the unintended_html_in_doc_comment rule, add unintended_html_in_doc_comment under linter > rules in your analysis_options.yaml file:

linter:
  rules:
    - unintended_html_in_doc_comment

If you're instead using the YAML map syntax to configure linter rules, add unintended_html_in_doc_comment: true under linter > rules:

linter:
  rules:
    unintended_html_in_doc_comment: true