[material_ui, cupertino_ui] Migrate several doc directives for demonstration

[dkwingsmt]

This PR migrates several doc directives to reach agreement before I perform a mass search-and-replace throughout the codebase.

To be exact, this PR migrates one {@tool snippet} directive, one {@tool dartpad} directive, and two {@tool sample} directives (which are actually all sample usages throughout the codebase).

The TODO comments are left for features to be implemented by the Dart team or unit tests that do not block the initial release.

Result

The result looks like this:

and

Known issue 1: No max-height for code snippets

It is a known flaw that the code blocks do not have a max height. The API doc page will display full source code, which is harder to read.

Solve it requires extra CSS rules, which is included in a previous proposal dart-lang/dartdoc#4243.

Known issue 2: dart analyze does not recognize the example directive

Even though dartdoc has supported the example directive, dart analyze still does not recognize it, causing warnings in IDE and CI. A PR dart-lang/sdk#63646 has been opened to solve this. Before the fix is landed in (hopefully) the next Dart version, we'll have to ignore this rule.

Pre-Review Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I linked to at least one issue that this PR fixes in the description above.
• I followed the version and CHANGELOG instructions, using semantic versioning and the repository CHANGELOG style, or I have commented below to indicate which documented exception this PR falls under¹.
• I updated/added any relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or I have commented below to indicate which test exemption this PR falls under¹.
• All existing and new tests are passing.

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.

Footnotes

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

[gemini-code-assist]

Code Review

This pull request updates the documentation in menu_anchor.dart and carousel.dart by replacing old tool blocks with {@example} directives and adding several TODO comments. The review feedback highlights that using regular comments (//) instead of doc comments (///) within documentation blocks breaks their contiguity, which can detach the API documentation. Additionally, the reviewer notes that the {@example} paths should not start with a leading slash to prevent resolution failures.

[justinmc]

Looks good as long as we have a way to know which examples need a live dartpad example in the future and which don't.

For the record here are how the 2 screenshots you showed above look today on the docs site. I think the new format looks good enough to me!

[justinmc]

The dartpads that you have removed appear to now be exactly the same as the samples that you removed (if I'm not overlooking something). Don't you need to distinguish the two so that we can add back the dartpads later?