Repository navigation
@docImports should support as imports #56527
Description
Something like this should work:
/// @docImport 'dart:io' as io;
library;
/// You can use [io.Stdin] to...
void foo() {
// intentionally left blank
}
Activity
dart-github-bot commentedon Aug 20, 2024
Summary: The
@docImportannotation currently doesn't support theaskeyword for aliasing imported libraries, making it difficult to reference imported symbols in documentation comments. This issue proposes adding support forasimports within@docImportannotations.[material_ui, cupertino_ui] Migrate `@macro`s that are defined in Mat…
szakarias commentedon Sep 29, 2026
This issue is central to the removal of dartdoc's universal scope (dart-lang/dartdoc#4283). Once dartdoc transitions to resolving doc comment references strictly through the analyzer (relying on the language's scope rules), references to library names will stop linking, as they currently rely on dartdoc's universal lookup fallback.
I strongly agree with @srawlins' proposal in #56528 to reference a library through its import prefix. It is the cleanest solution because it aligns with how the language already works: an import prefix is just a name in the library scope. This means the comment resolver wouldn't need a special case for library names. It also doesn't depend on
library foo;names. Like deferred imports, this would require the import prefix to be unique.I am currently fixing unresolved doc comment references in Flutter so that the
comment_referenceslint can be enabled (flutter/flutter#192870). On currentmain, all 24 remaining reports (in 12 files) need exactly this: library references and prefix-qualified references. Both of these groups are fixed by supportingason@docImport, so resolving this issue would cover #56528 as well.Regarding performance: @srawlins mentioned in dart-lang/dartdoc#3762 that an earlier attempt at supporting prefixes in
@docImportcaused a performance regression. @scheglov, could you take a look at whether there's a way to support this without that cost? CC @johnniwinther.scheglov commentedon Sep 29, 2026
Should
@docImportsupport full enhanced parts like functionality?Or just just
@docImportinside the library file, and all parts use it in documentation comments?FMorschel commentedon Sep 29, 2026
@scheglov follow this issue for that decision:
@docImports should work together #64261szakarias commentedon Sep 30, 2026
@scheglov Thanks for looking into this! I think we can start with just
@docImportinside the library file, with all parts using it in documentation comments. That covers the Flutter cases. Scoping doc imports per part file, like imports under enhanced parts, could be added later without breaking existing doc comments, since the library file's doc imports would remain visible in all parts.Side note: while looking into this, I noticed that
@docImports on apart ofdirective are currently parsed but silently ignored, without any diagnostic, even for a URI that doesn't exist. I'll file a separate issue for that.bwilkerson commentedon Sep 30, 2026
I still think that it could be confusing to users for
docImports to behave differently that normalimports and that it would be better to just add that support with theparts-with-importsfeature. If the behavior of 'Add import' and 'Add doc import' differ it will be harder for users to remember what they do.I don't know whether generated code usually includes comments (though if public APIs are being generated I certainly hope so). If it does, then we'll want code generators to be able to add local
docImports.scheglov commentedon Sep 30, 2026
I will implement
@docImportin parts too, so with enhanced parts support.bwilkerson commentedon Sep 30, 2026
Does that mean that
docImportin parts will be tied to theparts-with-importsfeature? (I think it's fine either way, just curious.)scheglov commentedon Sep 30, 2026
https://dart-review.googlesource.com/c/sdk/+/557680
@bwilkerson Yes.
@docImports on apart ofdirective are only used with theenhanced-parts(parts-with-imports) feature, and are then scoped like imports in parts: a part sees the doc imports of its enclosing files, can shadow them, and a doc import prefix in a part extends the enclosing prefix with the same name. Lookups still try the normal scope, including imports, first.Without the feature,
@docImports onpart ofare reported with a newdoc_import_in_part_filewarning, instead of being silently ignored as before, and only library@docImports are considered.bwilkerson commentedon Sep 30, 2026
Thanks!
DartDoc. Support for '@DocImport' in parts, prefixes, combinators.
scheglov commentedon Oct 1, 2026
https://dart-review.googlesource.com/c/sdk/+/558203
szakarias commentedon Oct 2, 2026
@scheglov This is great, thanks for the quick turnaround!
DartDoc. Add PrefixElement.scopeLibraries, report ambiguousCommentRef…