unintended_html_in_doc_comment

ドキュメントコメントで山括弧を使用すると、MarkdownによってHTMLとして扱われます。

HTMLタグやリンクを記述したい場合を除き、ドキュメントコメントで山括弧で囲まれたテキスト<…>を使用しないでください。

Markdownは、Markdownコードの一部としてHTMLタグを許可しているため、たとえばT<sub>1</sub>のように記述できます。Markdownは許可されるタグを制限するのではなく、単に出力にタグをそのまま含めます。

Dartdocは、既知の有効なHTMLタグのみを許可し、許可されていないHTMLタグは出力から省略します。許可されているタグとディレクティブのリストを以下で確認してください。ドキュメントコメントには、このリストにないHTMLタグを含めるべきではありません。

Markdownでは、たとえば<https://example.com/page.html>のように、<...>のみで区切られたURLへの「自動リンク」も記述できます。このようなリンクはDartdocでも許可されます。<...>で区切られたテキストは、2文字以上のスキーマで始まりコロンが続く有効な絶対URLである場合、自動リンクとみなされます。たとえば<mailto:mr_example@example.com>などです。

それ以外の<単語...>または</単語...>の出現は誤りの可能性が高く、このリンターはそれを警告します。HTMLタグのように見える場合（つまり<または</で始まり、その後に文字が続き、後で対応する>がある場合）、それが自動リンクであるか、または許可されているHTMLタグで始まらない限り、無効なHTMLタグとみなされます。

このような誤りは、たとえばコードスパンの外で型引数を持つDartコードを記述した場合に発生する可能性があります。たとえばList<int>型は...のように記述すると、<int>がHTMLタグのように見えます。コードスパンの終了引用符を忘れた場合も同様の効果があります。`List<int>型は...`のように記述すると、<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。

悪い例

/// 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マップ構文を使用してリンタールールを設定している場合は、linter > rulesの下にunintended_html_in_doc_comment: trueを追加します。

linter:
  rules:
    unintended_html_in_doc_comment: true