[Proposal] Lint rule or analyzer code for unresolved DartDoc symbols, post `@docImport` introduction

[navaronbracke]

With the new @docImport feature, I was looking for a way to have unresolved doc references be flagged, since we now have an extra option of dealing with this problem.

We do have #55414 for a similar case: Warn when a doc import is unused.

However, it would be nice if we had a rule for unresolved doc references in DartDoc.
For example:

/// This class references an unresolved class [Bar].
class Foo {}

This would warn on [Bar] not being found. It could suggest either:

• adding a @docImport
• importing the library normally
• fixing the reference if it was a typo or if the symbol no longer exists (which could be the case if docs were not updated)

I think that if we implement something like this, it could be very helpful for the quality of DartDoc in IDE's.

I'm not sure if this should become a code in the analyzer (like the issue mentioned above) or a lint rule.

[dart-github-bot]

Summary: The user proposes a new lint rule or analyzer code to flag unresolved DartDoc symbols, leveraging the @docImport feature. This would help improve DartDoc quality by identifying and suggesting fixes for unresolved references within documentation comments.

[pq]

/fyi @srawlins

[srawlins]

This is the comment_references lint rule.

[pq]

@navaronbracke: check out comment_references and if it doesn't work for you please re-open this request with more details. Thanks!

[navaronbracke]

TIL about that lint. Working as expected, thanks!