unintended_html_in_doc_comment

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

This rule is available as of Dart 3.5.

Rule sets: core, recommended, flutter

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\>`
/// <http://foo.bar.baz>

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

Unless stated otherwise, the documentation on this site reflects Dart 3.5.4. Page last updated on 2024-07-03. View source or report an issue.