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

錯誤示例 (BAD)

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

正確示例 (GOOD)

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