[cupertino_ui, material_ui] Fix bad doc references by Piinks · Pull Request #12381 · flutter/packages

Piinks · 2026-08-05T23:57:43Z

This fixes some bad doc references in material_ui and cupertino_ui
Explanations inline.

Pre-Review Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩²

flutter-dashboard · 2026-08-05T23:57:49Z

It looks like this pull request may not have tests. Please make sure to add tests or get an explicit test exemption before merging.

If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix?

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. If you believe this PR qualifies for a test exemption, contact "@test-exemption-reviewer" in the #hackers channel in Discord (don't just cc them here, they won't see it!). The test exemption team is a small volunteer group, so all reviewers should feel empowered to ask for tests, without delegating that responsibility entirely to the test exemption group.

Piinks · 2026-08-05T23:58:29Z

 ///    for a catalog of all Cupertino widgets.
 ///  * [flutter.dev/widgets](https://docs.flutter.dev/ui/widgets)
 ///    for a catalog of commonly-used Flutter widgets.
-/// @docImport 'package:flutter_test/flutter_test.dart';


We thought this could fix some references coming from the widgets library as it is re-exported (for now) from these packages. Since flutter_test is only a dev dependency, doc import will not work.

gemini-code-assist

Code Review

This pull request removes unresolvable doc imports (such as flutter_test and intl) and references to Intl.plural across the cupertino_ui and material_ui packages. It also defines a new macro template material_ui.paginated_data_table.primary in paginated_data_table.dart and references it in reorderable_list.dart. The reviewer noted that paginated_data_table.dart needs to be docImported in reorderable_list.dart to allow dartdoc to resolve the macro reference.

Piinks · 2026-08-05T23:58:38Z

 ///    for a catalog of commonly-used Material component widgets.
 ///  * [m3.material.io](https://m3.material.io/) for the Material 3 specification
 ///  * [m2.material.io](https://m2.material.io/) for the Material 2 specification
-/// @docImport 'package:flutter_test/flutter_test.dart';


We thought this could fix some references coming from the widgets library as it is re-exported (for now) from these packages. Since flutter_test is only a dev dependency, doc import will not work.

Piinks · 2026-08-06T00:01:29Z

 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

-/// @docImport 'package:intl/intl.dart';


Since package:intl is imported with a prefix intl the doc references to Intl.plural could not resolve (should be inlt.Intl.plural), which then propagated through all of the subclasses.

This was the cause of the bulk of the 1,400 doc reference issues we are seeing on pub.

The same was not true of cupertino_ui, turns out cupertino_ui does not even make the below references - because it is actually incorrect! So, I just removed them.

Piinks · 2026-08-06T00:01:40Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:01:44Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:01:49Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:01:55Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:02:00Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:02:05Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:02:10Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:02:16Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:02:21Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:02:24Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:02:28Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:02:33Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:02:39Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:02:44Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:02:48Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:02:51Z

  ///
  /// See also:
  ///
-  ///  * [Intl.plural], to which this form is passed.


See comment above.

Piinks · 2026-08-06T00:04:02Z

 // To regenerate the file, use:
 // dart script/l10n/bin/gen_localizations.dart --overwrite

-/// @docImport 'package:intl/intl.dart';


There are no references to intl in this file, and they would need the intl prefix as it is imported below anyways. removed since it is not needed.

Piinks · 2026-08-06T00:04:37Z

  final ScrollController? controller;

-  /// {@macro flutter.widgets.scroll_view.primary}
+  /// {@template material_ui.paginated_data_table.primary}


Fixes references to TargetPlatformVariant coming from widgets.dart, which cannot resolve in the dart docs for this package.

Piinks · 2026-08-06T00:04:53Z

 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

-/// @docImport 'package:flutter_test/flutter_test.dart';


Cannot resolve in this package.

Piinks · 2026-08-06T00:05:41Z

-/// By default, on [TargetPlatformVariant.desktop] platforms each item will
+/// By default, on desktop platforms each item will
 /// have a drag handle added on top of it that will allow the user to grab it
-/// to move the item. On [TargetPlatformVariant.mobile], no drag handle will be


Same as above, since these come from flutter_test and flutter_test references cannot be resolved since they are not a direct dev dependency, removed.

Piinks · 2026-08-06T00:06:02Z

  /// {@macro flutter.widgets.scroll_view.controller}
  final ScrollController? scrollController;

-  /// {@macro flutter.widgets.scroll_view.primary}


Updated for new macro that removes references to TargetPlatformVariant

dkwingsmt

LGTM. Thanks for the investigation!

@js

…r#190719) flutter/packages@4e3f83d...fc22143 2026-08-07 engine-flutter-autoroll@skia.org Roll Flutter (stable) from 058e0af to 6b182d2 (4 revisions) (flutter/packages#12394) 2026-08-07 269567208+reidbaker-agent@users.noreply.github.com [camera_android_camerax][tool] Migrate complexity checks to package:cognitive_complexity (flutter/packages#12356) 2026-08-06 mdebbar@google.com [camera_web] Remove invalid @js annotation on extension type constructors (flutter/packages#12384) 2026-08-06 tarrinneal@gmail.com [pigeon] add support for analyzer 13 and 14 (flutter/packages#12358) 2026-08-06 katelovett@google.com [cupertino_ui, material_ui] Fix bad doc references (flutter/packages#12381) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages-flutter-autoroll Please CC flutter-ecosystem@google.com on the revert to ensure that a human is aware of the problem. To file a bug in Flutter: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

[cupertino_ui, material_ui] Fix bad doc references

43850d3

flutter-dashboard Bot added the CICD Run CI/CD label Aug 5, 2026

github-actions Bot added triage-framework Should be looked at in framework triage p: cupertino_ui p: material_ui labels Aug 5, 2026

Piinks commented Aug 5, 2026

View reviewed changes

gemini-code-assist Bot reviewed Aug 5, 2026

View reviewed changes

Comment thread packages/material_ui/lib/src/reorderable_list.dart

Piinks commented Aug 5, 2026

View reviewed changes

Piinks commented Aug 6, 2026

View reviewed changes

Newlines and EOF

fa3d8aa

Piinks requested review from dkwingsmt and justinmc August 6, 2026 00:09

One more doc import, thanks G

28a1b8b

dkwingsmt approved these changes Aug 6, 2026

View reviewed changes

Piinks added the autosubmit Merge PR when tree becomes green via auto submit App label Aug 6, 2026

auto-submit Bot merged commit 17c97d0 into flutter:main Aug 6, 2026
13 checks passed

This was referenced Aug 7, 2026

Roll Packages from 4e3f83d37f83 to 142990b9f4d7 (3 revisions) flutter/flutter#190716

Closed

Roll Packages from 4e3f83d37f83 to fc22143c4490 (5 revisions) flutter/flutter#190719

Merged

Uh oh!

Conversation

Piinks commented Aug 5, 2026

Pre-Review Checklist

Footnotes

Uh oh!

flutter-dashboard Bot commented Aug 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkwingsmt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants