falconGitHub

unintended-html-in-doc-comment

Same as unintended_html_in_doc_comment in Dart lints

Group
Style
Path
lint/style/unintended-html-in-doc-comment
Default
On (recommended)
Origin
Dart lints
Rule
448 of 512
recommended

Flags angle-bracket text in doc comments that Markdown would render as an HTML tag.

Dart renders doc comments as Markdown, so an unbacktick-quoted <int> or List<int> is parsed as an HTML tag and silently dropped from the generated docs. The rule scans /// comment lines for <name sequences whose name is not a known HTML tag and is followed by a tag-like character (>, ,, <, or whitespace), which distinguishes a stray generic from real markup or a <https://...> autolink. Wrap such type references in backticks so they survive rendering. Fenced code blocks, indented code, and inline code spans are skipped.

Invalid

example.dartdart
/// Returns a List<int> of the parsed values.
/// Wraps a Future<void> completion.
/// Builds a Map<String, int> lookup table.
/// Emits a Stream<Event> of updates.
/// Backed by a Set<String> of keys.
class Api {}
Angle brackets will be interpreted as HTML.
1/// Returns a List<int> of the parsed values.
Angle brackets will be interpreted as HTML.
1/// Returns a List<int> of the parsed values.
2/// Wraps a Future<void> completion.
Angle brackets will be interpreted as HTML.
2/// Wraps a Future<void> completion.
3/// Builds a Map<String, int> lookup table.
Angle brackets will be interpreted as HTML.
3/// Builds a Map<String, int> lookup table.
4/// Emits a Stream<Event> of updates.
Angle brackets will be interpreted as HTML.
4/// Emits a Stream<Event> of updates.
5/// Backed by a Set<String> of keys.

Valid

example.dartdart
/// Returns a `List<int>` of the parsed values.
/// See <https://example.com> for the full reference.
/// Uses <code>inline</code> markup for emphasis.
/// True whenever a < b holds for the inputs.
/// Insert a hard line break here.<br>
/// Plain prose with no angle brackets at all.
class Api {}

Configure unintended-html-in-doc-comment

Set its severity in falcon.json. See the configuration guide.

falcon.jsonjson
{
  "linter": {
    "rules": {
      "style": {
        "unintended-html-in-doc-comment": "error"
      }
    }
  }
}

Or silence one occurrence with a suppression comment; the reason is required.

example.dartdart
// falcon-ignore lint/style/unintended-html-in-doc-comment: <reason>
  • unnecessary-await-in-returnunnecessary_await_in_return

    Avoid await on a returned Future the function's own Future already covers.

  • unnecessary-brace-in-string-interpsunnecessary_brace_in_string_interpsrecommended

    Flags ${x} string interpolations whose braces can be dropped.

  • unnecessary-breaksunnecessary_breaksrecommended

    Flags a trailing break in a switch case that already ends implicitly.

  • unnecessary-constructor-nameunnecessary_constructor_namerecommended

    Flags a redundant .new on constructor declarations and invocations.

  • unnecessary-finalunnecessary_final

    Don't use final for local variables and parameters.

  • unnecessary-lateunnecessary_laterecommended

    Flags a redundant late modifier on an initialized static or top-level variable.

  • unnecessary-library-directiveunnecessary_library_directiverecommended

    Flags a library directive that has neither a doc comment nor annotations.

  • unnecessary-library-nameunnecessary_library_namerecommended

    Flags a library directive that carries an explicit name.