unintended_html_in_doc_comment

O uso de colchetes angulares em um comentário de documentação é tratado como HTML pelo Markdown.

NÃO FAÇA usar texto entre colchetes angulares, <…>, em um comentário de documentação, a menos que você queira escrever uma tag HTML ou um link.

O Markdown permite tags HTML como parte do código Markdown, então você pode escrever, por exemplo, T<sub>1</sub>. O Markdown não restringe as tags permitidas; ele apenas inclui as tags literalmente na saída.

O Dartdoc permite apenas algumas tags HTML conhecidas e válidas, e omitirá da saída qualquer tag HTML não permitida. Veja a lista de tags e diretivas permitidas abaixo. O seu comentário de documentação não deve conter nenhuma tag HTML que não esteja nesta lista.

O Markdown também permite escrever um "auto-link" para uma URL, como por exemplo <https://example.com/page.html>, delimitado apenas por <...>. Esse link também é permitido pelo Dartdoc. Um texto delimitado por <...> é um auto-link se for uma URL absoluta válida, começando com um esquema de pelo menos dois caracteres seguido de dois-pontos, como <mailto:mr_example@example.com>.

Qualquer outra ocorrência de <palavra...> ou </palavra...> provavelmente é um erro, e este lint vai avisar sobre ela. Se algo parecer uma tag HTML, ou seja, começar com < ou </ seguido de uma letra, e tiver um > correspondente depois, então é considerado uma tag HTML inválida, a menos que seja um auto-link ou comece com uma tag HTML permitida.

Esse erro pode acontecer, por exemplo, ao escrever código Dart com argumentos de tipo fora de um trecho de código, como The type List<int> is ..., em que <int> parece uma tag HTML. Esquecer a crase de fechamento de um trecho de código pode ter o mesmo efeito: The type `List<int> is ... também tratará <int> como uma tag HTML.

Ao usar indentação para blocos de código, isso também pode ser causado por não indentar o suficiente. Blocos de código devem ser indentados com quatro espaços além do espaço que separa o comentário dos marcadores, embora o uso de crases triplas para blocos de código seja preferível à indentação.

Permite as seguintes diretivas HTML: comentários HTML, <!-- texto -->, instruções de processamento, <?...?>, seções CDATA e <[CDATA...]>. Permite links do DartDoc como [List<int>], que não aparecem depois de um ] nem antes de um [ ou (, e permite as seguintes tags HTML reconhecidas: 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 e wbr.

RUIM:

/// The type List<int>.
/// <assignment> -> <variable> = <expression>
///
///    List<int> func() => [];

BOM:

/// The type `List<int>`.
/// The type [List<int>]
/// `<assignment> -> <variable> = <expression>`
/// \<assignment\> -> \<variable\> = \<expression\>`
/// <https://example.com/example>
///
///     List<int> func() => [];
///
/// ```
/// List<int> func() => [];
/// ```

Para ativar a regra unintended_html_in_doc_comment, adicione unintended_html_in_doc_comment em linter > rules no seu arquivo analysis_options.yaml:

linter:
  rules:
    - unintended_html_in_doc_comment

Se você usa a sintaxe de mapa YAML para configurar as regras de lint, adicione unintended_html_in_doc_comment: true em linter > rules:

linter:
  rules:
    unintended_html_in_doc_comment: true