菜单
Best practices for validating Dart documentation comments. Covers using `dart doc` to catch unresolved references and macros.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | dart-doc-validation |
| description | Best practices for validating Dart documentation comments. Covers using `dart doc` to catch unresolved references and macros. |
| license | Apache-2.0 |
| key_features | ["Documentation comment validation","Unresolved reference checking","Dart doc macro verification"] |
Use this skill when:
///) in Dart code.To find documentation issues:
Verify if the comment_references lint is enabled:
analysis_options.yamlcomment_referencesRun the documentation generator to surface warnings:
dart doc -o $(mktemp -d)warning:, unresolved doc reference,
undefined macroIn your analysis_options.yaml, enable the comment_references lint.
linter:
rules:
- comment_references
Use the dart doc command with a temporary output directory to validate
documentation comments without polluting the local project workspace.
This command parses all documentation comments and reports warnings such as:
warning: unresolved doc referencewarning: undefined macroCommand to run:
dart doc -o $(mktemp -d)
This will work on Mac and Linux.
This ensures that the generated HTML files are stored in a temporary location and don't clutter the package directory, while still surfacing all validation warnings in the terminal output.
Browsing the docs:
Our docs use features designed to be run on a web server. If you want to browse
the generated docs locally, install the dhttpd package.
pub global activate dhttpd
TMP_DIR=$(mktemp -d) && dart doc -o "$TMP_DIR" && dhttpd --path "$TMP_DIR"
(Or use another HTTP server, such as python3 -m http.server.)
[Identifier]) correctly points to an existing class, method,
property, or parameter in the current scope or imported libraries.{@macro macro_name}, ensure that the
template {@template macro_name} is defined in the same file or a file
that is imported and visible to the documentation generator.Profile Dart command-line applications using the VM Service protocol to capture CPU samples and identify performance bottlenecks. Helps agents automate CPU profiling, generate function call breakdown summaries, and export JSON profiles without a browser or DevTools.
General best practices for Dart development. Covers code style, effective Dart, and language features.
Guidelines for handling long lines in Dart code to adhere to the 80-column rule. The `lines_longer_than_80_chars` lint.
Best practices for using `expect` and `package:matcher`. Focuses on readable assertions, proper matcher selection, and avoiding common pitfalls.
Guidelines for using modern Dart features (v3.0 - v3.10) such as Records, Pattern Matching, Switch Expressions, Extension Types, Class Modifiers, Wildcards, Null-Aware Elements, and Dot Shorthands.
Guidelines and best practices for refactoring consecutive prints, single-line string concatenations, and complex output blocks into triple-quoted multi-line string literals (''' or """) in Dart.