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

錯誤

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

良好

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

除非另有說明，否則本網站上的文件反映 Dart 3.7.1 版本。頁面最後更新於 2025-03-07。 檢視原始碼 或 回報問題。