Repository navigation
Make check_code_samples.dart support the standard example directives, and migrate some @tool directives - #189670
Conversation
github-actions
Bot
added
a: text input
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the dartdoc version in dev/bots/docs.sh and replaces {@tool dartpad} directives with tags and {@example} references across several widget files, adding region tags to the corresponding API examples. The review feedback points out that using double-slash '//' comments for TODOs inside documentation blocks breaks the contiguous doc comments in Dart, and recommends replacing them with triple-slash '///' comments to ensure the API documentation is generated correctly.
|
The analyzer still complains "doc_directive_unknown: Doc directive 'example' is unknown. - 237:9". dart-lang/sdk@7c1ca3f may solve this, or we might need dart-lang/sdk#63646. Anyhow, let's wait until the analyzer fix is rolled into Flutter before landing this. |
…tter into migrate-affected-templates
dkwingsmt
changed the title
@tool and used by material_ui or cupertino_uicheck_code_samples.dart support the standard example directives, and migrate some @tool directives
There was a problem hiding this comment.
Code Review
This pull request transitions API documentation examples from the legacy {@tool dartpad} format to the standard {@example} directive format wrapped in <callout-box> tags. It updates check_code_samples.dart and its tests to support and validate both legacy and standard style links, and updates the dartdoc version in docs.sh. The review feedback recommends replacing // comments with /// inside doc comment blocks to prevent block termination, improving the standardMalformedLinkRe regex to catch missing closing braces, and removing a misleading r prefix from the malformed link error message and its tests.
dkwingsmt
removed
a: text input
github-actions
Bot
added
a: text input
justinmc
left a comment
justinmc
left a comment
There was a problem hiding this comment.
LGTM 👍 . Sorry for the delay, I had an old review here that I realized I never submitted.
| String? alternateLink, | ||
| required bool useStandardStyle, | ||
| // "region" is the "#body" segment at the end of standard style links. | ||
| String? region, |
There was a problem hiding this comment.
Nit: Move useStandardStyle up so that the required parameters are together?
…tter into migrate-affected-templates
dkwingsmt
added
the
autosubmit
flutter-dashboard
Bot
removed
the
autosubmit
2 participants
This PR consists of two parts of changes.
Migrate some
@tooldirectivesAs part of #189629, this PR migrates specific templates used by the
material_uiandcupertino_uipackages from{@tool}directives to standard dartdoc to ensure they render correctly within these packages. This migration is limited to only these essential{@tool}instances, as Dartdoc does not currently provide native support for Dartpad.Note that Dartpad notices ("To see it in action, copy and run this code snippet on Dartpad") are expanded, unlike in flutter/packages#12120 where they're macros. This is necessary because Dartdoc can't correctly handle nested templates and macros, preventing inner macros from expanding correctly.
This PR will be followed by reverting flutter/packages#12271, which constitutes the final step of #189629. I have verified that the package docs will render correctly after the revert.
Make
check_code_samples.dartsupport the standard example directivesSince the examples now consist of two styles, the legacy style "See code in" and the standard style
@example,check_code_samples.dartneeds to be updated to recognize the standard@exampledirectives so that it won't incorrectly report that these examples files are not used by any docs.Pre-launch Checklist
///).If you need help, consider asking for advice on the #hackers-new channel on Discord.
If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.
Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the
gemini-code-assistbot 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.