内容

文档注释中意外的 HTML

内容

Markdown 将文档注释中的尖括号视为 HTML。

此规则自 Dart 3.5 起可用。

规则集：核心、推荐、Flutter

详细信息

#

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

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

Dartdoc 仅允许某些已知和有效的 HTML 标签，并将从输出中省略任何不允许的 HTML 标签。请参阅下面允许的标签和指令列表。您的文档注释不应包含此列表中不存在的任何 HTML 标签。

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

<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 和 wbr。

错误

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

正确

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

analysis_options.yaml
yaml
linter:
  rules:
    - unintended_html_in_doc_comment

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