Skip to content

Fix doc references to Material and Cupertino in the widgets library and its tests - #193334

Merged
szakarias merged 2 commits into
flutter:masterfrom
szakarias:fix-widgets-material-doc-references
Sep 28, 2026
Merged

Fix doc references to Material and Cupertino in the widgets library and its tests#193334
szakarias merged 2 commits into
flutter:masterfrom
szakarias:fix-widgets-material-doc-references

Conversation

@szakarias

@szakarias szakarias commented Sep 25, 2026

Copy link
Copy Markdown
Contributor

Adds @docImport 'package:flutter/material.dart' / 'package:flutter/cupertino.dart' for doc references that currently resolve only through dartdoc's global lookup. This is an interim fix; these (and the existing) doc imports will need to change once the long-term solution in #181288 is decided.

Note: Widget tests are checked for Material and Cupertino imports (dev/bots/check_tests_cross_imports.dart), but the check does not cover doc imports. If you'd rather not doc import Material in widget tests, I can put the names in backticks instead.

Towards #192870 — enabling the comment_references lint.

@szakarias
szakarias requested a review from justinmc September 25, 2026 08:57
@flutter-dashboard flutter-dashboard Bot added the CICD Run CI/CD label Sep 25, 2026
@github-actions github-actions Bot added framework flutter/packages/flutter repository. See also f: labels. a: accessibility Accessibility, e.g. VoiceOver or TalkBack. (aka a11y) f: scrolling Viewports, list views, slivers, etc. labels Sep 25, 2026
gemini-code-assist[bot]
gemini-code-assist Bot reviewed Sep 25, 2026
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds @docImport statements to several widget files and test files to facilitate documentation generation. The review comments suggest using backticks for references in private files and test files to avoid unnecessary cross-layer imports and library; headers, and recommend grouping @docImport statements consistently without empty lines.

Comment thread packages/flutter/lib/src/widgets/_accessibility_evaluations.dart
Comment on lines +5 to +6
/// @docImport 'package:flutter/material.dart';
library;

@gemini-code-assist gemini-code-assist Bot Sep 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Since _accessibility_evaluations.dart is a private implementation file, it does not generate public API documentation. To avoid introducing cross-layer doc imports (referencing material.dart from the widgets layer) and adding unnecessary library; headers, it is highly recommended to use backticks (e.g., `Material`) for these references instead of brackets. This satisfies the comment_references lint without violating layering boundaries.

Comment thread packages/flutter/lib/src/widgets/orientation_builder.dart
Comment thread packages/flutter/lib/src/widgets/radio_group.dart
Comment thread packages/flutter/lib/src/widgets/sliver_clip.dart
Comment thread packages/flutter/test/widgets/autocomplete_test.dart
Comment thread packages/flutter/test/widgets/selectable_region_test.dart
Comment thread packages/flutter/test/widgets/sliver_fill_remaining_test.dart
Comment thread packages/flutter/test/widgets/two_dimensional_scroll_view_test.dart
justinmc
justinmc approved these changes Sep 25, 2026
View reviewed changes

@justinmc justinmc left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍 . When we resolve #181288 we will migrate these to material_ui and cupertino_ui, but for now this is the right move.

@szakarias
szakarias added this pull request to the merge queue Sep 28, 2026
Merged via the queue into flutter:master with commit a89783e Sep 28, 2026
18 checks passed
@szakarias
szakarias deleted the fix-widgets-material-doc-references branch September 28, 2026 08:31
DanTup pushed a commit to DanTup/flutter that referenced this pull request Sep 28, 2026
@szakarias @DanTup
Fix doc references to Material and Cupertino in the widgets library a…
2aa0449 
…nd its tests (flutter#193334)

Adds `@docImport 'package:flutter/material.dart'` /
`'package:flutter/cupertino.dart'` for doc references that currently
resolve only through dartdoc's global lookup. This is an interim fix;
these (and the existing) doc imports will need to change once the
long-term solution in flutter#181288
is decided.

Note: Widget tests are checked for Material and Cupertino imports
(`dev/bots/check_tests_cross_imports.dart`), but the check does not
cover doc imports. If you'd rather not doc import Material in widget
tests, I can put the names in backticks instead.

Towards flutter#192870 — enabling the
`comment_references` lint.
This was referenced Sep 28, 2026
Closed
Closed
Closed
DanTup pushed a commit to DanTup/flutter that referenced this pull request Sep 28, 2026
@szakarias @DanTup
Fix doc references to Material and Cupertino in the widgets library a…
b7c9cd8 
…nd its tests (flutter#193334)

Adds `@docImport 'package:flutter/material.dart'` /
`'package:flutter/cupertino.dart'` for doc references that currently
resolve only through dartdoc's global lookup. This is an interim fix;
these (and the existing) doc imports will need to change once the
long-term solution in flutter#181288
is decided.

Note: Widget tests are checked for Material and Cupertino imports
(`dev/bots/check_tests_cross_imports.dart`), but the check does not
cover doc imports. If you'd rather not doc import Material in widget
tests, I can put the names in backticks instead.

Towards flutter#192870 — enabling the
`comment_references` lint.
This was referenced Sep 28, 2026
Closed
Merged
auto-submit Bot pushed a commit to flutter/packages that referenced this pull request Sep 29, 2026
@engine-flutter-autoroll
Manual roll Flutter from 4fcd90be0045 to c5a061b18fa2 (222 revisions) (…
08e1067 
…#13060)

Manual roll Flutter from 4fcd90be0045 to c5a061b18fa2 (222 revisions)

Manual roll requested by [email protected]

flutter/flutter@4fcd90b...c5a061b

2026-09-28 [email protected] [cross imports] navigator_test.dart (flutter/flutter#190954)
2026-09-28 [email protected] Revert: Reland: Only render views that need to be rendered  (flutter/flutter#193360)
2026-09-28 [email protected] ci(bringup): android_intent_security_test is green (flutter/flutter#193469)
2026-09-28 [email protected] Sync CHANGELOG.md from stable (flutter/flutter#193020)
2026-09-28 [email protected] Roll Fuchsia Linux SDK from ukukV5lEkKabtOATk... to QdgqP02_cYpRQQQNN... (flutter/flutter#193454)
2026-09-28 [email protected] Roll pub packages (flutter/flutter#193460)
2026-09-28 [email protected] Un-nest sceneBuildDuration and windowRenderDuration in web SceneBuilderRecorder (flutter/flutter#193260)
2026-09-28 [email protected] Fix unresolved doc comment references in dev/integration_tests and dev/benchmarks (flutter/flutter#193433)
2026-09-28 [email protected] Roll Packages from e55e7ac to ba0364a (9 revisions) (flutter/flutter#193450)
2026-09-28 [email protected] [tool] Require explicit dependency injection for FlutterDevice and FlutterDevice.create (flutter/flutter#192830)
2026-09-28 [email protected] Roll pub packages (flutter/flutter#193442)
2026-09-28 [email protected] [flutter_tools] Include data assets from hooks when pubspec.yaml is empty (flutter/flutter#193434)
2026-09-28 [email protected] Roll pub packages (flutter/flutter#193438)
2026-09-28 [email protected] Fix unresolved doc comment references in Material and Cupertino (flutter/flutter#193283)
2026-09-28 [email protected] Fix doc references to Material and Cupertino in the widgets library and its tests (flutter/flutter#193334)
2026-09-26 [email protected] wasm: enforce WasmGC opt-in capability checks and Firefox < 147 guard (flutter/flutter#193180)
2026-09-26 [email protected] [Android] Refuse external setters of engine entrypoint and cached engine arguments via `Intent`s (flutter/flutter#190249)
2026-09-26 [email protected] [web] Unskip TextPainter.getWordBoundary test (flutter/flutter#193378)
2026-09-26 [email protected] Specify non-obvious types in pattern variable declarations (flutter/flutter#192632)
2026-09-26 [email protected] Removes feedback loop from advanced filters without offscreen msaa and framebufferfetch (flutter/flutter#193306)
2026-09-26 [email protected] [web] Unskip 8 passing image tests in painting and rendering (flutter/flutter#193377)
2026-09-26 [email protected] Revert: Allow resetting test invariants in `addTearDown` (flutter/flutter#193383)
2026-09-25 [email protected] [tool] Migrate CoverageCollector to modular dependency injection (flutter/flutter#192924)
2026-09-25 [email protected] Fix more unresolved doc comment references (flutter/flutter#193336)
2026-09-25 [email protected] Allow resetting test invariants in `addTearDown` (flutter/flutter#192082)
2026-09-25 [email protected] [a11y] Add a semantics role for slider (flutter/flutter#193324)
2026-09-25 [email protected] Fix plugin tests after Pigeon plugin template changes (flutter/flutter#193302)
2026-09-25 [email protected] [Android 17] Bump Standard Test Apps in flutter/flutter to AGP 9.3.1 (flutter/flutter#193263)
2026-09-25 [email protected] SSBO-based gradients in UberSDF (flutter/flutter#192962)
2026-09-25 [email protected] [Linux] Handle FlView being destroyed before rendering is complete. (flutter/flutter#193268)
2026-09-25 [email protected] [flutter_tools] Handle Windows reserved characters in test target path (flutter/flutter#191900)
2026-09-25 [email protected] docs(tools): nit: say hook/build.dart in CMake native assets comment (flutter/flutter#192205)
2026-09-25 [email protected] [web] Enable Firefox Skwasm UI CI suites, configure COI configs, and fail fast on loader rejections (flutter/flutter#193187)
2026-09-25 [email protected] [Android 17] Bumped Engine Dependencies to 9.3.1 (flutter/flutter#193265)
2026-09-25 [email protected] [web] Omit group role on menu scrollables and assign region role to named routes (flutter/flutter#192965)
2026-09-25 [email protected] Roll Skia from 8eedeed98e79 to f441ca223b2b (5 revisions) (flutter/flutter#193353)
2026-09-25 [email protected] Roll Fuchsia Linux SDK from EbPpoJW-Lnsu-8dyZ... to ukukV5lEkKabtOATk... (flutter/flutter#193326)
2026-09-25 [email protected] Roll Packages from 431ea69 to e55e7ac (6 revisions) (flutter/flutter#193351)
2026-09-25 [email protected] Support DynamicLibrary.codeAsset in Flutter (flutter/flutter#188947)
2026-09-25 [email protected] Roll Dart SDK from 75d9e87d4e3d to 0e7642b85457 (1 revision) (flutter/flutter#193346)
2026-09-25 [email protected] Exclude iOS PRs from macOS link (flutter/flutter#193315)
2026-09-25 [email protected] Roll Skia from 6357608543ec to 8eedeed98e79 (4 revisions) (flutter/flutter#193341)
2026-09-25 [email protected] Roll Dart SDK from d3aedb186aab to 75d9e87d4e3d (3 revisions) (flutter/flutter#193335)
2026-09-25 [email protected] Cache the paint offset adjusted line metrics in TextPainter (flutter/flutter#191223)
...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@justinmc justinmc justinmc approved these changes
+1 more reviewer
@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

a: accessibility Accessibility, e.g. VoiceOver or TalkBack. (aka a11y) CICD Run CI/CD f: scrolling Viewports, list views, slivers, etc. framework flutter/packages/flutter repository. See also f: labels.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@szakarias @justinmc