[cupertino_ui] Migrate api sample code to @example dartdoc directive by Piinks · Pull Request #12063 · flutter/packages

Piinks · 2026-06-29T23:21:39Z

Migrates @tool directives to @example in cupertino_ui
Towards flutter/flutter#172936 and flutter/flutter#172937

Referenced: https://github.com/flutter/packages/pull/11975/files

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. ↩ ↩²

gemini-code-assist

Code Review

This pull request replaces {@tool dartpad} and {@tool snippet} blocks with {@example} directives across various Cupertino widgets, adds temporary TODO comments, and configures analysis_options.yaml to ignore doc_directive_unknown warnings. The feedback points out that using // instead of /// for the TODO comments breaks the contiguous doc comment blocks, which will cause the main widget descriptions to be omitted from the generated API documentation. Additionally, the reviewer notes that the paths in the {@example} directives should be relative to the package root by removing the leading slash.

gemini-code-assist · 2026-06-29T23:23:08Z

+// TODO(dkwingsmt): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+///
 /// This example shows how [CupertinoActivityIndicator] can be customized.
 ///
-/// ** See code in examples/api/lib/cupertino/activity_indicator/cupertino_activity_indicator.0.dart **
-/// {@end-tool}
+/// {@example /example/lib/activity_indicator/cupertino_activity_indicator.0.dart}
+///
+// TODO(dkwingsmt): End of the blue example container.


In Dart, any line starting with // (instead of ///) breaks the contiguous block of doc comments. This causes the doc comment block before the // TODO to be detached from the class/member declaration, meaning the main description of the widget/class will be completely missing from the generated API documentation.

To prevent this, use /// for the TODO comments to keep the doc comment block contiguous. Additionally, the path in {@example} should be relative to the package root (e.g., example/lib/... instead of /example/lib/...), as a leading slash can cause resolution issues. This issue is present across almost all files in this PR and should be fixed everywhere.

Suggested change

// TODO(dkwingsmt): Replace the following block with a blue example container

// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243

///

/// This example shows how [CupertinoActivityIndicator] can be customized.

///

/// ** See code in examples/api/lib/cupertino/activity_indicator/cupertino_activity_indicator.0.dart **

/// {@end-tool}

/// {@example /example/lib/activity_indicator/cupertino_activity_indicator.0.dart}

///

// TODO(dkwingsmt): End of the blue example container.

/// TODO(dkwingsmt): Replace the following block with a blue example container

/// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243

///

/// This example shows how [CupertinoActivityIndicator] can be customized.

///

/// {@example example/lib/activity_indicator/cupertino_activity_indicator.0.dart}

///

/// TODO(dkwingsmt): End of the blue example container.

Is that true?

It might be, but I think we want that anyways. There will be no blue box initially so the line break will distinguish the separation of the code block from the rest of the docs?

gemini-code-assist · 2026-06-29T23:23:08Z

+// TODO(dkwingsmt): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+///
 /// This example shows how [CupertinoLinearActivityIndicator] can be customized.
 ///
-/// ** See code in examples/api/lib/cupertino/activity_indicator/cupertino_linear_activity_indicator.0.dart **
-/// {@end-tool}
+/// {@example /example/lib/activity_indicator/cupertino_linear_activity_indicator.0.dart}
+///
+// TODO(dkwingsmt): End of the blue example container.


Using // breaks the contiguous doc comment block, detaching the main description of CupertinoLinearActivityIndicator from its declaration. Use /// instead to keep the block contiguous, and remove the leading slash from the {@example} path.

Suggested change

// TODO(dkwingsmt): Replace the following block with a blue example container

// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243

///

/// This example shows how [CupertinoLinearActivityIndicator] can be customized.

///

/// ** See code in examples/api/lib/cupertino/activity_indicator/cupertino_linear_activity_indicator.0.dart **

/// {@end-tool}

/// {@example /example/lib/activity_indicator/cupertino_linear_activity_indicator.0.dart}

///

// TODO(dkwingsmt): End of the blue example container.

/// TODO(dkwingsmt): Replace the following block with a blue example container

/// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243

///

/// This example shows how [CupertinoLinearActivityIndicator] can be customized.

///

/// {@example example/lib/activity_indicator/cupertino_linear_activity_indicator.0.dart}

///

/// TODO(dkwingsmt): End of the blue example container.

gemini-code-assist · 2026-06-29T23:23:08Z

+// TODO(dkwingsmt): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+// TODO(dkwingsmt): Add unit tests to this code snippet.
+// https://github.com/flutter/flutter/issues/188530


Using // breaks the contiguous doc comment block, detaching the main description of CupertinoApp from its declaration. Use /// instead to keep the block contiguous.

/// TODO(dkwingsmt): Replace the following block with a blue example container /// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 /// TODO(dkwingsmt): Add unit tests to this code snippet. /// https://github.com/flutter/flutter/issues/188530

gemini-code-assist · 2026-06-29T23:23:08Z

+// TODO(dkwingsmt): End of the blue example container.
+///
+// TODO(dkwingsmt): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+// TODO(dkwingsmt): Add unit tests to this code snippet.
+// https://github.com/flutter/flutter/issues/188530


Using // breaks the contiguous doc comment block. Use /// instead to keep the block contiguous.

/// TODO(dkwingsmt): End of the blue example container. /// /// TODO(dkwingsmt): Replace the following block with a blue example container /// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 /// TODO(dkwingsmt): Add unit tests to this code snippet. /// https://github.com/flutter/flutter/issues/188530

gemini-code-assist · 2026-06-29T23:23:08Z

+// TODO(dkwingsmt): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+///
 /// This example shows a [CupertinoTabBar] placed in a [CupertinoTabScaffold].
 ///
-/// ** See code in examples/api/lib/cupertino/bottom_tab_bar/cupertino_tab_bar.0.dart **
-/// {@end-tool}
+/// {@example /example/lib/bottom_tab_bar/cupertino_tab_bar.0.dart}
+///
+// TODO(dkwingsmt): End of the blue example container.


Using // breaks the contiguous doc comment block, detaching the main description of CupertinoTabBar from its declaration. Use /// instead to keep the block contiguous, and remove the leading slash from the {@example} path.

/// TODO(dkwingsmt): Replace the following block with a blue example container /// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 /// /// This example shows a [CupertinoTabBar] placed in a [CupertinoTabScaffold]. /// /// {@example example/lib/bottom_tab_bar/cupertino_tab_bar.0.dart} /// /// TODO(dkwingsmt): End of the blue example container.

gemini-code-assist · 2026-06-29T23:23:08Z

+// TODO(dkwingsmt): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+///
 /// This sample shows produces an enabled and disabled [CupertinoButton] and
 /// [CupertinoButton.filled].
 ///
-/// ** See code in examples/api/lib/cupertino/button/cupertino_button.0.dart **
-/// {@end-tool}
+/// {@example /example/lib/button/cupertino_button.0.dart}
+///
+// TODO(dkwingsmt): End of the blue example container.


Using // breaks the contiguous doc comment block, detaching the main description of CupertinoButton from its declaration. Use /// instead to keep the block contiguous, and remove the leading slash from the {@example} path.

/// TODO(dkwingsmt): Replace the following block with a blue example container /// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 /// /// This sample shows produces an enabled and disabled [CupertinoButton] and /// [CupertinoButton.filled]. /// /// {@example example/lib/button/cupertino_button.0.dart} /// /// TODO(dkwingsmt): End of the blue example container.

justinmc

Looks good minus my comment about distinguishing dartpad blocks. And I think Gemini is wrong about its double slash concern?

justinmc · 2026-06-30T03:59:02Z

-/// {@tool dartpad}
+// TODO(dkwingsmt): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243


I think we need a TODO that's different for dartpad vs. snippet, so that we can distinguish them later when we put the dartpads back. See discussion here: #11975 (comment)

Oh good call! Let me update marking which ones were dartpads. 👍

justinmc · 2026-06-30T03:59:30Z

+// TODO(dkwingsmt): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243
+///
 /// This example shows how [CupertinoActivityIndicator] can be customized.
 ///
-/// ** See code in examples/api/lib/cupertino/activity_indicator/cupertino_activity_indicator.0.dart **
-/// {@end-tool}
+/// {@example /example/lib/activity_indicator/cupertino_activity_indicator.0.dart}
+///
+// TODO(dkwingsmt): End of the blue example container.


Is that true?

dkwingsmt

LGTM except for some minor places. Thank you Kate for working on this!

On a stricter note: While the current resolution for dartpads are

// TODO: Migrate the following block to dartpad
/// ...
// TODO: end of dartpad

My guess is that the following way is closer to the eventual format, hence slightly easier for the future migration:

// TODO: Start of blue container
/// ...
// TODO: Migrate the following directive to dartpad
/// ...
// TODO: end of blue container

However, this is no big deal. It's just a global find-and-replace away and we can still do it when we actually migrate to the blue containers. We should proceed with the current way to unblock the first release.

dkwingsmt · 2026-06-30T17:31:20Z

 // `_SlideTarget`s.
 //
-// TODO(dkwingsmt): It should recompute hit testing when the app is updated,
+// TODO(framework): It should recompute hit testing when the app is updated,


Unintentional change? Reverting:

Suggested change

// TODO(framework): It should recompute hit testing when the app is updated,

// TODO(dkwingsmt): It should recompute hit testing when the app is updated,

Oh ok! I guess I felt odd making all these TODOs yours. :)

justinmc

LGTM 👍

dkwingsmt

The issue link in the dartpad TODOs should be changed to https://github.com/dart-lang/dartdoc/issues/4123

Piinks · 2026-07-01T16:53:08Z

+///
 /// This sample demonstrates how to use [CupertinoTextMagnifier].
 ///
 /// ** See code in examples/api/lib/widgets/magnifier/cupertino_text_magnifier.0.dart **


This is a widgets example, I think I need to bring this sample code over. FYI @dkwingsmt we should check that there aren't samples from the widgets/* or other libraries in the material_ui version of this.

Piinks · 2026-07-01T16:53:17Z

+///
 /// This sample demonstrates how to use [CupertinoMagnifier].
 ///
 /// ** See code in examples/api/lib/widgets/magnifier/cupertino_magnifier.0.dart **


This one too

Piinks · 2026-07-01T16:54:47Z

+  ///
  /// This sample demonstrates how to customize the magnifier that this text field uses.
  ///
  /// ** See code in examples/api/lib/widgets/text_magnifier/text_magnifier.0.dart **


This one too

Piinks · 2026-07-01T17:22:01Z

Added missing samples in #12086. I'll push a PR in flutter/flutter as well to keep sync.

dkwingsmt · 2026-07-01T21:45:04Z

@Piinks Can you address #12063 (review) ?

Piinks · 2026-07-01T21:50:41Z

@Piinks Can you address (earlier review) ?

Yup, I already did, I just haven't pushed it yet because I need to add the missing samples as well from #12086

Piinks · 2026-07-01T21:52:19Z

Which just merged! 🎊 Updating now

dkwingsmt

Also, menu_anchor.dart contains the only two instances of @tool sample. I've linked how they should be converted.

dkwingsmt · 2026-07-01T21:56:46Z

 /// [CupertinoColors.systemRed].
 ///
-/// {@tool sample}
+// TODO(framework): Replace the following block with a @dartpad directive


This is a @tool sample, not a dartpad.

Here's how I think it should be converted:
https://github.com/flutter/packages/pull/11975/changes#diff-d3032846508ffdddebef87d9bbdb1fe55360296bbd1b2a010d1de6e8ded91cc8R298

dkwingsmt · 2026-07-01T21:56:55Z

 ///
 /// ## Usage
-/// {@tool sample}
+// TODO(framework): Replace the following block with a @dartpad directive


This is a @tool sample, not a dartpad.

Here's how I think it should be converted:
https://github.com/flutter/packages/pull/11975/changes#diff-d3032846508ffdddebef87d9bbdb1fe55360296bbd1b2a010d1de6e8ded91cc8R298

Piinks · 2026-07-01T22:10:32Z

Ah shoot, I think when I did a find and replace to update the dart issue links, I replaced ones I did not mean to.
@dkwingsmt can you confirm - dart-lang/dartdoc#4123 is for dartpad and dart-lang/dartdoc#4243 should be for the blue container ones?

Piinks · 2026-07-01T22:13:18Z

can you confirm - dart-lang/dartdoc#4123 is for dartpad and dart-lang/dartdoc#4243 should be for the blue container ones?

I am pretty sure I am right. Updating.

dkwingsmt · 2026-07-01T22:19:52Z

Ah shoot, I think when I did a find and replace to update the dart issue links, I replaced ones I did not mean to. @dkwingsmt can you confirm - dart-lang/dartdoc#4123 is for dartpad and dart-lang/dartdoc#4243 should be for the blue container ones?

Yes, the issues are right.

dkwingsmt · 2026-07-01T22:21:15Z

 ///
-/// {@tool snippet}
+// TODO(framework): Replace the following block with a blue example container
+// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123


4123 is the dartpad issue :(

Yup, as I said, I noticed some were updated incorrectly when I did a find and replace. Just pushed a new commit

dkwingsmt

LGTM. Thank you!

@tool

…12078) Migrates @tool directives to @example in material_ui Towards flutter/flutter#172936 and flutter/flutter#172937 Prerequisite: * #12092, which moves missing sample files. Related: * #12063, which migrates `cupertino_ui` ## Pre-Review Checklist **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). 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. [^1]: 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 Bot added the CICD Run CI/CD label Jun 29, 2026

github-actions Bot added triage-framework Should be looked at in framework triage p: cupertino_ui labels Jun 29, 2026

Piinks changed the title ~~Migrate Cupertino api code to @example dartdoc directive~~ [cupertino_ui] Migrate api sample code to @example dartdoc directive Jun 29, 2026

gemini-code-assist Bot reviewed Jun 29, 2026

View reviewed changes

Piinks requested review from dkwingsmt and justinmc June 29, 2026 23:26

justinmc reviewed Jun 30, 2026

View reviewed changes

Piinks force-pushed the cupertinoApiCode branch from a7d3e82 to be5aa6e Compare June 30, 2026 15:39

github-actions Bot removed the CICD Run CI/CD label Jun 30, 2026

Piinks requested a review from justinmc June 30, 2026 16:49

dkwingsmt approved these changes Jun 30, 2026

View reviewed changes

justinmc approved these changes Jun 30, 2026

View reviewed changes

dkwingsmt requested changes Jun 30, 2026

View reviewed changes

dkwingsmt mentioned this pull request Jun 30, 2026

[material_ui] Migrate api sample code to @example dartdoc directive #12078

Merged

11 tasks

Piinks commented Jul 1, 2026

View reviewed changes

dkwingsmt self-requested a review July 1, 2026 21:05

justinmc added the CICD Run CI/CD label Jul 1, 2026

dkwingsmt mentioned this pull request Jul 1, 2026

[material_ui] Move over more API samples #12092

Merged

11 tasks

Piinks added 4 commits July 1, 2026 16:55

Migrate cupertino_ui doc comments to @example

6207aef

Update analysis comment

7e5c974

Update cupertino_ui sample code migration TODOs

d615ec5

Update dart-lang issue links

762ce22

dkwingsmt reviewed Jul 1, 2026

View reviewed changes

Piinks added 2 commits July 1, 2026 17:01

Update missing sample directives

402446e

Update prior @sample directives to proper wrappers

ce9f17d

Piinks force-pushed the cupertinoApiCode branch from be5aa6e to ce9f17d Compare July 1, 2026 22:06

github-actions Bot removed the CICD Run CI/CD label Jul 1, 2026

dkwingsmt mentioned this pull request Jul 1, 2026

[material_ui, cupertino_ui] Migrate several doc directives for demonstration #11975

Closed

11 tasks

dkwingsmt reviewed Jul 1, 2026

View reviewed changes

Correct dart issue links for blue containers

832b548

Piinks requested a review from dkwingsmt July 1, 2026 22:29

Piinks added the CICD Run CI/CD label Jul 1, 2026

dkwingsmt approved these changes Jul 1, 2026

View reviewed changes

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

auto-submit Bot merged commit ab5051f into flutter:main Jul 1, 2026
89 checks passed

	// TODO(framework): It should recompute hit testing when the app is updated,
	// TODO(dkwingsmt): It should recompute hit testing when the app is updated,

Uh oh!

Conversation

Piinks commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-Review Checklist

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 29, 2026

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!

gemini-code-assist Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

justinmc left a comment

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 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkwingsmt Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

justinmc left a comment

Choose a reason for hiding this comment

Uh oh!

dkwingsmt left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Piinks commented Jul 1, 2026

Uh oh!

dkwingsmt commented Jul 1, 2026

Uh oh!

Piinks commented Jul 1, 2026

Uh oh!

Piinks commented Jul 1, 2026

Uh oh!

dkwingsmt left a comment

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

Piinks commented Jun 29, 2026 •

edited

Loading

dkwingsmt left a comment •

edited

Loading

dkwingsmt Jun 30, 2026 •

edited

Loading

dkwingsmt left a comment •

edited

Loading