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 注释 、处理指令 <?...?>、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 和 wbr。

错误示例

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

正确示例

dart/// 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

analysis_options.yaml
yamllinter:
  rules:
    - unintended_html_in_doc_comment

如果你改为使用 YAML 映射语法来配置 linter 规则，请在 linter > rules 下添加 unintended_html_in_doc_comment: true

analysis_options.yaml
yamllinter:
  rules:
    unintended_html_in_doc_comment: true

除非另有说明，否则本网站上的文档反映的是 Dart 3.7.1 版本。页面上次更新于 2025-03-07。查看源代码或报告问题。

unintended_html_in_doc_comment

详情

启用