unintended_html_in_doc_comment

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

此规则自 Dart 3.5 版本起可用。

_规则集：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:[email protected]>.

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>

要启用 unintended_html_in_doc_comment 规则，请在你的 analysis_options.yaml 文件中，在 linter > rules 下添加 unintended_html_in_doc_comment ：

linter:
  rules:
    - unintended_html_in_doc_comment

除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面最后更新于 2025-02-05。 查看源代码 或 报告问题.