New lint for doc imports

[FMorschel]

After a small discussion on both #59724 and #59723 I feel like we could have a lint that suggests converting a normal import into a doc import if it is not being used anywhere else besides doc comments. Maybe to remove a doc import if it is already imported normally too? Something like organize_doc_imports (if it does the second part if not, prefer_doc_imports is probably better) or something (name suggestions are appreciated).

---

@bwilkerson wrote on #59722 (comment):

we're essentially not adding any new lints at this time that aren't requested by the language team, typically in order to facilitate adoption of new language features.

I'm unsure if this is "a new language feature" and if this is important enough to be considered (and I'm not from the language team hahaha) but I'm fine with waiting.

[bwilkerson]

There is some room for judgement here, and doc imports are a feature that probably needs some additional support, but we should have a holistic design that takes enhanced-parts into account.

@srawlins

[FMorschel]

Just to reference it here properly, I've opened #59759 to make the quick fixes for comment_references to add doc imports instead of normal imports.

[FMorschel]

@srawlins talked about these points at dart-lang/dartdoc#3935 (comment):

• reporting unused doc-imports
• reporting imports that could be doc-imports

I'm also suggesting:

• reporting doc-imports that are unnecessary (opposite as above)

[bwilkerson]

Sorry, I focused too much on the suggestion that this be done via lints. In my mind "lint" has a very specific meaning: a diagnostic that is disabled by default. I'm not convinced that that's the right UX. We generally use a lint when there's some ambiguity or a chance for false positives, and in this case there isn't.

However, the need for additional diagnostics to improve the UX around normal and dc imports is undisputed.

That said, I think we need to do some UX design work around imports in light of enhanced parts, and I think it would be more efficient if that design also accounted for the UX related to doc imports. In other words, I'd like to have a plan for what UX we want to support given both changes to the language and then plan steps to get there, rather than taking steps that seem good in isolation but that might not be optimal in the long run.

[FMorschel]

That said, I think we need to do some UX design work around imports in light of enhanced parts

About that, I was wondering where would auto-complete and quick-fixes add imports now. Currently, I believe they would add it all to the main file, but if we have a three-level part library (a(b(c))) and we trigger them at the lowest file (c), will it add to the main file(a), to the part that is the main for the third (b) or at the third (c)?

Is there an issue to discuss anything related to that?

[bwilkerson]

Yes, that's one of the UX questions that needs to be considered.

No, I don't think we have an issue to discuss it. I find it hard to do design in a thread (issue, email, chat, etc.) because I can't remove the noise once we start making concrete decisions, and I can't tell which aspects of the design are still incomplete. I do want to hear from the community, but a doc feels like a much better forum for proposing and refining designs. I suppose we can start in an issue, but I'll want to move the discussion at some point.