Repository navigation
Description
Dart docImports allow you to reference identifiers from outside of the current file using square brackets in Dart Doc. The framework contains many of these that reference Material or Cupertino and will need to be migrated before decoupling can be completed.
What should we do about problematic docImports?
docImports are problematic when they reference Material or Cupertino from outside of that referenced library. For example, widgets/scrollbar.dart references both Material and Cupertino so that it can refer to things like [Scrollbar] and [CupertinoScrollbar] in its docs.
flutter/packages/flutter/lib/src/widgets/scrollbar.dart
Lines 5 to 6 in 3b20617
| /// @docImport 'package:flutter/cupertino.dart'; | |
| /// @docImport 'package:flutter/material.dart'; |
Option 0: Do nothing
This is not viable in the long term because it will break dart doc after Material and Cupertino are removed from flutter/flutter. The references in the example above to material.dart and cupertino.dart will not be found.
In the short term immediately after decoupling, because we plan to keep the original Material and Cupertino code in flutter/flutter during a deprecation period, it will not break anything. However, users that click on these links in the framework docs will be taken to the deprecated versions of this code, which is misleading.
Option 1: Remove affected docImports
We could remove the problematic docImports and replace the linked identifiers with unlinked inline code. In the scrollbar.dart example above, we would remove the two docImports and replace [Scrollbar] with `Scrollbar`.
This is an imperfect solution because users of our docs would lose a lot of useful links.
Options 2: Migrate each problematic docImport to reference the new external package
We would have to add a dev dependency on material_ui and cupertino_ui, and it's unclear if this would cause any problems.
Where are problematic docImports located?
Problematic docImports have been seen in the following places, but they may also exist elsewhere:
- packages/flutter_test
- packages/flutter/test
- packages/flutter/lib/src/widgets
- packages/flutter/lib/src/material
- packages/flutter/lib/src/cupertino
How can we prevent this problem in the future?
We should ideally include a lint that can catch problematic docImports, similar to what was done for cross-library test imports in #178693.
Links
This was discovered by @navaronbracke in: https://github.com/flutter/flutter/pull/180456/files#r2700767565
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsNo status
Activity
dkwingsmt commentedon Jan 30, 2026
Are you sure they're not supported? I see some
docImportof other packages. For example, https://api.flutter.dev/flutter/flutter_test/testWidgets.html referencesFuturefromdart:asyncandLeakTesting.settingsfrompackage:leak_tracker_testing. It seems that the the entire doc for the related packages are generated and included (instead of referencing their own doc website (understandably)), which works despite not seeming optimally space efficient.navaronbracke commentedon Jan 30, 2026
dart:asyncis a core library, though. (which should always work) AndtestWidgetsworks, because of the dependency: https://github.com/flutter/flutter/blob/main/packages/flutter_test/pubspec.yaml#L39dkwingsmt commentedon Jan 31, 2026
I'm sure it needs to involve some kind of dependency. Would it work if we add
materialandcupertinoasdev_dependencies?flutter-triage-bot commentedon Jun 6, 2026
This issue is marked P1 but has had no recent status updates.
The P1 label indicates high-priority issues that are at the top of the work list. This is the highest priority level a bug can have if it isn't affecting a top-tier customer or breaking the build. Bugs marked P1 are generally actively being worked on unless the assignee is dealing with a P0 bug (or another P1 bug). Issues at this level should be resolved in a matter of months and should have monthly updates on GitHub.
Please consider where this bug really falls in our current priorities, and label it or assign it accordingly. This allows people to have a clearer picture of what work is actually planned. Thanks!
[-]Migrate cross-library docImports before decoupling[/-][+][Decoupling] Migrate cross-library docImports[/+]justinmc commentedon Sep 24, 2026
It seems we should add dev dependencies on material_ui and cupertino_ui to packages/flutter/pubspec.yaml. We should watch out for possible side effects though: 1. Will changes to
widgetsetc. that break material_ui or cupertino_ui cause a CI failure now? Maybe that's ok, we shouldn't break them anyway. 2. Will this cause any problems in google3?dkwingsmt commentedon Sep 24, 2026
Looking at it now I think the framework should migrate away from these references, because the libraries are just customers to these basic widgets, which shouldn't appoint them as the major purpose. Maybe in appropriate cases you can reference them in "See also" as "excellent examples", in which case you can reference by URLs.
Fix doc references to Material and Cupertino in the widgets library a…
Fix doc references to Material and Cupertino in the widgets library a…
Fix doc references to Material and Cupertino in the widgets library a…