[mustache_template] Adopt code-excerpts for README - #40
Conversation
Replaces the hand-written Dart snippets in the README with <?code-excerpt?> pragmas backed by example/lib/readme_excerpts.dart, so they're validated against compilable, analyzed source instead of free-hand text. This surfaced two pre-existing doc bugs: an incomplete-tag Template literal that threw at parse time, and a lambda example block that was an exact copy-paste duplicate of the one before it (now removed). Also drops the package's ci_config.yaml, whose only purpose was opting it out of that validation. Fixes flutter/flutter#183936 FPOCTSMP-8
560787a to
f94effd
Compare
There was a problem hiding this comment.
Code Review
This pull request adopts "code-excerpt" for the "mustache_template" package's README Dart snippets. It extracts the inline code snippets from "README.md" into a new compilable example file "readme_excerpts.dart" under a new "example" package, references them in the README using code-excerpt tags, removes the "exempt_from_excerpts" CI opt-out, and bumps the package version to 2.0.6. There are no review comments, so I have no feedback to provide.
Thanks; I'll review this one as well since it's not clear how quickly that one might reach a landable state. |
stuartmorgan-g
left a comment
There was a problem hiding this comment.
Mostly looks good, just a couple of comments.
…, trim CHANGELOG - Renames example/lib/readme_excerpts.dart to example/lib/main.dart per review feedback, since the example app can just show what's in the README directly. - Fixes the analysis failures: helper functions are private (no public API to document), the immutable template string is const, and every renderString() call site gets an explicit String type per specify_nonobvious_local_variable_types. - Drops the ci_config.yaml CHANGELOG line; that's an internal CI mechanism, not something relevant to package clients. FPOCTSMP-8
f701421 to
2dc70b2
Compare
Replaces the hand-written Dart snippets in
mustache_template's README with<?code-excerpt?>pragmas backed by a newexample/lib/readme_excerpts.dart, so every snippet is validated against compilable, analyzed source instead of free-hand text (dart pub global run flutter_plugin_tools update-excerpts/validateboth pass clean).This surfaced two pre-existing doc bugs:
Template('{{# foo }}')in the first lambda example had no closing tag, so it threw a parse error the moment it was actually executed.<b>PUB</b>lambda examples were an exact copy-pasted duplicate; the duplicate is removed.Also removes
ci_config.yaml, whose only purpose was opting the package out of excerpt validation (see #102679-style TODO in the file) — no longer needed now that the README is excerpt-backed.Note on overlap: flutter/flutter#183936 already has two other open PRs addressing it — #23 and #36. This PR was written independently and additionally removes the
ci_config.yamlexemption, which neither of those does. Happy to have maintainers close this in favor of one of those if that's preferred; flagging here so reviewer time isn't wasted on duplicate review.Fixes flutter/flutter#183936
Pre-Review Checklist
[vector_math]///).This PR only touches the README, CHANGELOG, an example app, and a CI opt-out file — no package source changed, so it falls under the documentation/example test exemption. The new
example/lib/readme_excerpts.dartis exercised directly (dart run) as part of verifying this change, and every existing test in the package (dart test, 252 tests) still passes.FPOCTSMP-8
Footnotes
Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩2