Rules / Style / unintended-html-in-doc-comment
unintended-html-in-doc-comment
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 {}
How to configure
Set the severity of unintended-html-in-doc-comment in your falcon.json:
falcon.jsonjson
{
"linter": {
"rules": {
"style": {
"unintended-html-in-doc-comment": "error"
}
}
}
}
