Dart Doc Validation

dart-doc-validation

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

kevmoo/dash_skills·161installs147starsDocumentation

SKILL.md

Full skill instructions

Dart Doc Validation

1. When to use this skill

Use this skill when:

Writing or updating documentation comments (///) in Dart code.
Checking for broken documentation links, references, or macros.
Preparing a package for publishing to pub.dev.

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.

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

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.

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/kevmoo/dash_skills --skill dart-doc-validation

View on GitHub

dart-doc-validation

More Documentation skills

View all

Documentation

lark-wiki

Manage Lark Wiki spaces, members, nodes, and document organization hierarchies.

17.5K 457.5K

View

Documentation

lark-openapi-explorer

Discover and call native Lark OpenAPI endpoints from official documentation when existing skills fall short.

17.5K 451K

View

Documentation

supabase-postgres-best-practices

Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.

2.7K 431.1K

View

Documentation

writing-beats

writing beats

276.6K 414.7K

View

Documentation

writing-shape

writing shape

276.6K 414.2K

View

Documentation

writing-fragments

writing fragments

276.6K 413.9K

View

Documentation

writing-plans

Comprehensive implementation plans for multi-step tasks, breaking down specs into bite-sized, testable steps.

295.4K 268K

View

Documentation

writing-skills

Test-driven documentation for creating reusable agent techniques, patterns, and reference guides.

295.4K 205.7K

View

Documentation

firebase-auth-basics

Guide for setting up and using Firebase Authentication. Use this skill when the user's app requires user sign-in, user management, or secure data access using auth rules.

462 163.8K

View

Documentation

Builds and deploys Firebase SQL Connect (aka Firebase Data Connect) backends with PostgreSQL securely. Use when designing schemas with tables and relations, writing authorized queries and mutations, configuring real-time data updates, or generating type-safe SDKs. Use when you need a relational database with Firebase, or when the user mentions SQL Connect or Data Connect.

462 158.3K

View

Documentation

vercel-react-view-transitions

Guide for implementing smooth, native-feeling animations using React's View Transition API (`<ViewTransition>` component, `addTransitionType`, and CSS view transition pseudo-elements). Use this skill whenever the user wants to add page transitions, animate route changes, create shared element animations, animate enter/exit of components, animate list reorder, implement directional (forward/back) navigation animations, or integrate view transitions in Next.js. Also use when the user mentions view transitions, `startViewTransition`, `ViewTransition`, transition types, or asks about animating between UI states in React without third-party animation libraries.

31.9K 143K

View