Repository navigation
comment_references lint incorrectly flags references to library name #64540
Description
Flutter uses reference to library name in its api doc
https://github.com/flutter/flutter/blob/7c548a2a9ae5e086000de7bbf4d4cdb2fe6ca6d7/packages/flutter/lib/src/rendering/object.dart#L2228
Where the [widgets] should link to the https://api.flutter.dev/flutter/widgets/ in dart doc, but the comment_references lint still flags it as false positive.
Activity
bwilkerson commentedon Oct 8, 2026
Yes. The solution we came to with the dartdoc team is that we will support defining an import prefix on a
docImportand support a comment reference that uses the prefix.I believe that file can be made to work (under those rules) by using a doc import of the form
/// @docImport 'package:flutter/widgets.dart' as widgets;The analyzer package was recently updated to support this form, and I think that should have rolled into Flutter, so you ought to be able to test this in your IDE today if you're using a recent enough build.
chunhtai commentedon Oct 8, 2026
it fixes this case but will force all the other references from widgets library to be prefixed by
widgets.it is not a clean workaround.unless the norm will be something like
bwilkerson commentedon Oct 8, 2026
Yeah, that's kind of ugly.
@szakarias @srawlins
natebosch commentedon Oct 9, 2026
FWIW I don't think the workaround is unreasonable and this situation is likely to be very rare, but if we think a solution is feasible without incurring too much new complexity I'm happy to wait for it to land before we put the lint into the recommended set.
szakarias commentedon Oct 9, 2026
I can see why it reads a bit odd, but I actually don't think of the two imports as a workaround. They do different jobs. Comment references follow Dart scoping, and the only name a library has in scope is an import prefix, so the prefixed doc import is how you name the library. The plain doc import brings the library's members into scope for unqualified references. Without it, every reference into that library would have to be qualified, and the prefix would appear everywhere, in the comment and in the rendered docs, which hurts readability. Qualifying a few references where disambiguation is needed is the same choice you have with regular imports, and it can be made per file; the prefix is then visible in the link text, as it already is for regular prefixed imports.
It's also rare in practice: about 20 references in 12 files across all of flutter/flutter, all handled in flutter/flutter#193906, and the generated API docs link them the same as before. These are the last reports outside engine; the plan has been to enable the lint once that PR lands, so it doesn't block enabling the lint in Flutter. I wouldn't hold the recommended set for it either.
cc @johnniwinther
lrhn commentedon Oct 10, 2026
As @szakarias says, that's exactly what we do in normal imports. It is the idiomatic way to give a fresh name that can be used to avoid conflicts and also no prefix where there is no conflict.
It'd be weirder to do the same thing in a different way for DartDoc.
Whether you use
showandhideis a matter of taste, and whether you want the conflicted name to be used unprefixed from the other source.(Will the prefix be visible in the generated docs?)
FMorschel commentedon Oct 10, 2026
Great question, I'm not sure either.
@DanTup @srawlins @keertip what do you think about:
I think that now these are more stable and have been here for a while we could think about the above. Making it clearer that they are not just text.
goderbauer commentedon Oct 12, 2026
Prior discussion on this: #56528
DanTup commentedon Oct 12, 2026
I think there's value in those, though completion would likely be much more involved than the colouring (which I expect is fairly trivial).
(we should probably have any discussion about that issue in that issue though, to avoid unnecessary noise here)
chunhtai commentedon Oct 12, 2026
I am ok adapting the double import, but it feels weird that lint and dartdoc are out of sync in this case.