unintended_html_in_doc_comment

在文档注释中使用尖括号会被 Markdown 视为 HTML。

不要在文档注释中使用带尖括号的文本，例如 <…>，除非你想编写 HTML 标签或链接。

Markdown 允许将 HTML 标签作为 Markdown 代码的一部分，因此你可以编写例如 T<sub>1</sub>。Markdown 不限制允许的标签，它只是将标签原样包含在输出中。

Dartdoc 只允许一些已知且有效的 HTML 标签，并且会忽略输出中任何不允许的 HTML 标签。请参阅下面的允许标签和指令列表。你的文档注释不应包含此列表之外的任何 HTML 标签。

Markdown 还允许你编写指向 URL 的“自动链接”，例如 <https://example.com/page.html>，仅由 <...> 分隔。Dartdoc 也允许此类链接。如果由 <...> 分隔的文本是有效的绝对 URL，以至少两个字符的方案后跟冒号开头，例如 <mailto:mr_example@example.com>，则它是一个自动链接。

任何其他出现 <word...> 或 </word...> 的情况都可能是错误，并且此 lint 会对此发出警告。如果某些内容看起来像 HTML 标签，即以 < 或 </ 后跟一个字母开头，并且后面有匹配的 >，则除非它是自动链接或以允许的 HTML 标签开头，否则会被视为无效 HTML 标签。

此类错误可能会发生，例如在代码块之外编写带有类型参数的 Dart 代码时，例如 The type List<int> is ...，其中 <int> 看起来像一个 HTML 标签。缺少代码块的结束引号也会产生同样的效果：The type `List<int> is ... 也会将 <int> 视为一个 HTML 标签。

允许以下 HTML 指令：HTML 注释，<!-- text -->；处理指令，<?...?>；CDATA 节，以及 <[CDATA...]>。允许 DartDoc 链接，例如 [List<int>]，这些链接不在 ] 之后或 [ 或 ( 之前，并允许以下可识别的 HTML 标签：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>

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

linter:
  rules:
    - unintended_html_in_doc_comment

如果你使用的是 YAML map 语法来配置 linter 规则，请在 linter > rules 下添加 unintended_html_in_doc_comment: true

linter:
  rules:
    unintended_html_in_doc_comment: true