dart-doc-validation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dart Doc Validation

Dart文档校验

1. When to use this skill

1. 何时使用本指南

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.

当你遇到以下场景时可参考：

编写或更新Dart代码中的文档注释（
```
///
```
）。
检查损坏的文档链接、引用或宏。
准备将包发布到pub.dev。

2. Best Practices

2. 最佳实践

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:

bash

dart doc -o $(mktemp -d)

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.

使用带临时输出目录的

dart doc

命令来校验文档注释，不会污染本地项目工作区。

该命令会解析所有文档注释并上报如下警告：

```
warning: unresolved doc reference
```
```
warning: undefined macro
```

运行命令：

bash

dart doc -o $(mktemp -d)

这确保生成的HTML文件存储在临时位置，不会打乱包目录，同时仍会在终端输出中展示所有校验警告。

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.

未解析的文档引用：确保所有被方括号（
```
[Identifier]
```
）包裹的标识符都正确指向当前作用域或已导入库中存在的类、方法、属性或参数。
未定义的宏：如果使用了
```
{@macro macro_name}
```
，请确保
```
{@template macro_name}
```
模板定义在同一文件中，或者定义在文档生成器可导入并可见的文件中。