Add a warning similar to `UNUSED_IMPORT` for doc imports that are unused.

[kallentu]

Currently, you can add doc imports to any library whether or not it's used in any references.

/// @docImport 'libb.dart'; // unused and has no warning
library a;

/// Test doc comment
class A {}

It would be nice to have it report UNUSED_IMPORT or UNUSED_DOC_IMPORT when the doc import isn't being used for any reference resolving so we can avoid unnecessary doc imports (and also see that it will actively be used).

cc. @srawlins @goderbauer

[goderbauer]

It should probably also warn if libb.dart is imported as a regular import and hence its doc import is unnecessary/duplicated?

Loosely related: It would also be nice to warn on regular imports if they are only used for a doc reference. The warning should tell people to use a doc import instead.

[bwilkerson]

It would be nice to have it report UNUSED_IMPORT or UNUSED_DOC_IMPORT when the doc import isn't being used ...

Agreed. I'd lean toward making it a new diagnostic (UNUSED_DOC_IMPORT sgtm) because I think that the problem message, correction message, diagnostic documentation, and fixes are all likely to be different.

It should probably also warn if libb.dart is imported as a regular import and hence its doc import is unnecessary/duplicated?

Loosely related: It would also be nice to warn on regular imports if they are only used for a doc reference. The warning should tell people to use a doc import instead.

Yes, and yes.

[FMorschel]

Loosely related: It would also be nice to warn on regular imports if they are only used for a doc reference. The warning should tell people to use a doc import instead.

I think #59741 would be the issue for this.

[FMorschel]

I'll take a look at this to see if I can implement it

[srawlins]

Note that this is, I believe, a tricky one.

Whether imports are used or not depends on the Elements for the imports. And right now doc-imports do not have Elements. They don't participate in the element model.

I tried once to get doc-imports into the element model, in https://dart-review.googlesource.com/c/sdk/+/387861, and it lead to an analysis slow-down for the flutter/flutter repo, so it is reverted. I suspect this is because when doc-imports are included in the calculation of library cycles, the library cycles get huge in flutter/flutter, because they already have hundreds of doc-imports in the codebase. And because the very nature of doc-imports is that you are often doc-importing "downstream" code which depends on the code being documented. So it often creates bigger loops.

It's possible that @scheglov's work on fine-grained dependencies can help here. It might mean that larger library cycles (due to doc-imports) are not as expensive to analyze as they used to be.

[FMorschel]

Alright, thanks for the heads up.

Should we think about other warnings like ambiguous_import too?