意外的html在文档注释中

详情
用法

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

此规则从 Dart 3.5 开始可用。

不要在文档注释中使用尖括号文本 <…>，除非您想编写 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 注释 ，处理指令 <?...?>，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
yamllinter:
  rules:
    - unintended_html_in_doc_comment

除非另有说明，本网站上的文档反映的是 Dart 3.6.0。页面上次更新时间为 2024-07-03。查看源代码或报告问题。

意外的html在文档注释中

详情

用法