proposal: `dartdoc_macro_reference`

[rrousselGit]

dartdoc_macro_reference

Description

"Only use macros with pre-defined templates"

Details

Currently, there is no safeguard for dartdoc macros.

When writing:

/// {@macro whatever}
var x;

there is nothing that checks whatever matches with a valid {@template whatever} defined previously.

So if a typo is made when using the macro, or if somehow during refactoring a template is renamed/removed, this would break the documentation.

A lint cold be added to verify that the macro string correctly has a template

Kind

info, like most of the other lints

Good Examples

/// {@template whatever}
/// {@endtemplate}
var a;

/// {@macro whatever} // "whatever" correctly exists as a template
var b;

Bad Examples

/// {@template whatever}
/// {@endtemplate}
var a;

/// {@macro not_found} 
     ^^^^^^^ // There's no template with the key "not_found"
var b;

[srawlins]

Does dartdoc not produce a warning? That would be my recommendation. Dartdoc produces many warnings, and I don't think we should reproduce them in the linter.

[rrousselGit]

I don't know if dartdoc produces a warning or not, but it certainly doesn't show-up in the IDE.
A lint would mean that it both shows up in the "problems" tab and in the source code.

There's already a lint for dartdoc-related mistakes: comment_references. But it's about /// [UnknownType] not macros.
So I think this is reasonable

[bwilkerson]

comment_references is about the analyzer's ability to provide navigation, which is more limited that dartdoc's ability to provide navigation (in other words, comment_references will flag references that dartdoc can handle without an additional import). We would eventually like to make the two behave the same, but that work hasn't been scheduled yet.

[parlough]

Not sure if it has support for this currently, but this may be something package:daco would be well suited to provide in its analyzer plugin.

[srawlins]

This rule would only benefit people contributing to the flutter/flutter or flutter/engine repositories, right?

[rrousselGit]

This rule would only benefit people contributing to the flutter/flutter or flutter/engine repositories, right?

No, it's something available to everyone.

I'm personally using macros in my packages, and I'm sure many do so too.
The feature is not well known, but it's quite convenient.

[srawlins]

OK cool