dart-doc-validation

Name: dart-doc-validation
Author: kevmoo

231installs16forks

How to install dart-doc-validation?

kevmoo/dash_skills/dart-doc-validation

$npx -y skills add kevmoo/dash_skills --skill dart-doc-validation

Installs into the current project.

Summary

Best practices for validating Dart documentation comments. Covers using dart doc to catch unresolved references and macros.

Files · 1

View on GitHub

SKILL.md

1	# Dart Doc Validation
2
3	## 1. When to use this skill
4
5	Use this skill when:
6	- Writing or updating documentation comments (`///`) in Dart code.
7	- Checking for broken documentation links, references, or macros.
8	- Preparing a package for publishing to pub.dev.
9
10	## Discovery
11
12	To find documentation issues:
13
14	### Missing Lint
15	Verify if the `comment_references` lint is enabled:
16	- Target: `analysis_options.yaml`
17	- Search Query: `comment_references`
18
19	### Automated Validation
20	Run the documentation generator to surface warnings:
21	- Command: `dart doc -o $(mktemp -d)`
22	- Keywords to look for: `warning:`, `unresolved doc reference`,
23	`undefined macro`
24
25	## 2. Best Practices
26
27	### Enable the doc validation lint
28
29	In your `analysis_options.yaml`, enable the `comment_references` lint.
30
31	```yaml
32	linter:
33	rules:
34	- comment_references
35	```
36
37	### Validating Documentation Locally
38
39	Use the `dart doc` command with a temporary output directory to validate
40	documentation comments without polluting the local project workspace.
41
42	This command parses all documentation comments and reports warnings such as:
43	- `warning: unresolved doc reference`
44	- `warning: undefined macro`
45
46	Command to run:
47
48	```bash
49	dart doc -o $(mktemp -d)
50	```
51
52	This will work on Mac and Linux.
53
54	This ensures that the generated HTML files are stored in a temporary location
55	and don't clutter the package directory, while still surfacing all validation
56	warnings in the terminal output.
57
58	Browsing the docs:
59
60	Our docs use features designed to be run on a web server. If you want to browse
61	the generated docs locally, install the `dhttpd` package.
62
63
64	```shell
65	pub global activate dhttpd
66	TMP_DIR=$(mktemp -d) && dart doc -o "$TMP_DIR" && dhttpd --path "$TMP_DIR"
67	```
68
69	(Or use another HTTP server, such as `python3 -m http.server`.)
70
71
72	### Fixing Common Warnings
73
74	- Unresolved doc reference: Ensure that any identifier wrapped in square
75	brackets (`[Identifier]`) correctly points to an existing class, method,
76	property, or parameter in the current scope or imported libraries.
77	- Undefined macro: If using `{@macro macro_name}`, ensure that the
78	template `{@template macro_name}` is defined in the same file or a file
79	that is imported and visible to the documentation generator.

People who liked this also viewed

6 picks

Type

hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026262k37k
request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026165k181k
analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026161k507
explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026161k507
ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026160k181k
scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026149k181k

dart-doc-validation

231installs16forks

View on GitHub

How to install dart-doc-validation?

kevmoo/dash_skills/dart-doc-validation

$npx -y skills add kevmoo/dash_skills --skill dart-doc-validation

Installs into the current project.

Summary

Best practices for validating Dart documentation comments. Covers using dart doc to catch unresolved references and macros.

Files · 1

View on GitHub

SKILL.md

1	# Dart Doc Validation
2
3	## 1. When to use this skill
4
5	Use this skill when:
6	- Writing or updating documentation comments (`///`) in Dart code.
7	- Checking for broken documentation links, references, or macros.
8	- Preparing a package for publishing to pub.dev.
9
10	## Discovery
11
12	To find documentation issues:
13
14	### Missing Lint
15	Verify if the `comment_references` lint is enabled:
16	- Target: `analysis_options.yaml`
17	- Search Query: `comment_references`
18
19	### Automated Validation
20	Run the documentation generator to surface warnings:
21	- Command: `dart doc -o $(mktemp -d)`
22	- Keywords to look for: `warning:`, `unresolved doc reference`,
23	`undefined macro`
24
25	## 2. Best Practices
26
27	### Enable the doc validation lint
28
29	In your `analysis_options.yaml`, enable the `comment_references` lint.
30
31	```yaml
32	linter:
33	rules:
34	- comment_references
35	```
36
37	### Validating Documentation Locally
38
39	Use the `dart doc` command with a temporary output directory to validate
40	documentation comments without polluting the local project workspace.
41
42	This command parses all documentation comments and reports warnings such as:
43	- `warning: unresolved doc reference`
44	- `warning: undefined macro`
45
46	Command to run:
47
48	```bash
49	dart doc -o $(mktemp -d)
50	```
51
52	This will work on Mac and Linux.
53
54	This ensures that the generated HTML files are stored in a temporary location
55	and don't clutter the package directory, while still surfacing all validation
56	warnings in the terminal output.
57
58	Browsing the docs:
59
60	Our docs use features designed to be run on a web server. If you want to browse
61	the generated docs locally, install the `dhttpd` package.
62
63
64	```shell
65	pub global activate dhttpd
66	TMP_DIR=$(mktemp -d) && dart doc -o "$TMP_DIR" && dhttpd --path "$TMP_DIR"
67	```
68
69	(Or use another HTTP server, such as `python3 -m http.server`.)
70
71
72	### Fixing Common Warnings
73
74	- Unresolved doc reference: Ensure that any identifier wrapped in square
75	brackets (`[Identifier]`) correctly points to an existing class, method,
76	property, or parameter in the current scope or imported libraries.
77	- Undefined macro: If using `{@macro macro_name}`, ensure that the
78	template `{@template macro_name}` is defined in the same file or a file
79	that is imported and visible to the documentation generator.

People who liked this also viewed

6 picks

Type