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.