dart-doc-validation

Dart ドキュメントの検証

1. このスキルを使用するタイミング

次の場合にこのスキルを使用します。

• Dart コード内のドキュメントコメント（///）を作成または更新するとき。
• ドキュメントのリンク、参照、マクロの切れを確認するとき。
• pub.dev で公開するためのパッケージを準備するとき。

使用しない場合（適用を控えるためのガイドライン）

次の場合は、このスキルを適用したり、ドキュメントコメントをリファクタリングしたりしないでください。

• 説明用の疑似コードと Dart 以外のコードフェンス：コメントに疑似コードや Dart 以外の言語識別子（例：yaml`、json、````bash）が含まれている場合、 ````text`), or abstract conceptual fragments intentionally not designed to compile as valid Dart.
• Generated Code: Files generated by tools (e.g. *.g.dart, *.mocks.dart, *.freezed.dart) where comments are synthesized.
• External Markdown Hyperlinks: Text in square brackets followed by a link target (e.g. [External Guide](https://...)), which is standard Markdown hyperlink syntax rather than an unresolved Dart doc reference.

Discovery

To find documentation issues:

Missing Lint

Verify if the comment_references lint is enabled:

• Target: analysis_options.yaml
• Search Query: comment_references

Automated Validation

Run the documentation generator to surface warnings:

• Command: dart doc -o $(mktemp -d)
• Keywords to look for: warning:, unresolved doc reference, undefined macro

2. Best Practices

Enable the doc validation lint

In your analysis_options.yaml, enable the comment_references lint.

linter:
  rules:
    - comment_references

Validating Documentation Locally

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 reference
• warning: undefined macro

Command 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.

dart install 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.)

Fixing Common Warnings

• Unresolved doc reference: Ensure that any identifier wrapped in square brackets ([Identifier]) correctly points to an existing class, method, property, or parameter in the current scope or imported libraries.
• Undefined macro: If using {@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.