unintended_html_in_doc_comment

在文件註解中使用角括號會被 Markdown 視為 HTML。

此規則自 Dart 3.5 起可用。

規則集：core、recommended、flutter

請勿在文件註解中使用角括號文字 <…>，除非您想要撰寫 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...> 的情況都可能是錯誤，並且此程式碼檢查會對其發出警告。如果某些內容看起來像 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\>`
/// <http://foo.bar.baz>

若要啟用 unintended_html_in_doc_comment 規則，請在您的 analysis_options.yaml 檔案中的 linter > rules 下新增 unintended_html_in_doc_comment。

linter:
  rules:
    - unintended_html_in_doc_comment

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