用途
本技能用于校验 Dart 代码中的文档注释（///），帮助发现文档中的失效引用、未解析链接和未定义宏，适合在编写或更新文档注释、检查文档链接与宏、以及准备将包发布到 pub.dev 时使用。
主要能力
- 发现文档问题：检查 analysis_options.yaml 中是否启用了 comment_references lint；运行文档生成器以暴露警告。
- 自动化校验：运行
dart doc -o $(mktemp -d)，关注输出中的warning:、unresolved doc reference、undefined macro等关键词。 - 本地校验文档：使用带临时输出目录的
dart doc命令，在不污染项目工作区的情况下解析所有文档注释并报告警告。 - 浏览生成的文档：文档功能设计为在 Web 服务器上运行，如需本地浏览，可安装 dhttpd 包。
- 修复常见警告：针对未解析的文档引用和未定义的宏给出处理方向。
使用方式
启用文档校验 lint：在 analysis_options.yaml 中启用 comment_references 规则：
linter:
rules:
- comment_references
本地校验文档：使用临时输出目录运行：
dart doc -o $(mktemp -d)
该命令会解析所有文档注释并报告如下警告：
warning: unresolved doc reference
warning: undefined macro
此方式适用于 Mac 和 Linux，生成的 HTML 文件存放在临时位置，不会弄乱包目录，同时仍会在终端输出中暴露所有校验警告。
浏览文档：文档使用为在 Web 服务器上运行而设计的功能。如需在本地浏览生成的文档，安装 dhttpd 包：
dart install dhttpd
TMP_DIR=$(mktemp -d) && dart doc -o "$TMP_DIR" && dhttpd --path "$TMP_DIR"
（或使用其他 HTTP 服务器，例如 python3 -m http.server。）
修复常见警告：
- 未解析的文档引用：确保方括号包裹的标识符（[Identifier]）正确指向当前作用域或已导入库中存在的类、方法、属性或参数。
- 未定义的宏：如果使用
{@macro macro_name}，确保模板{@template macro_name}定义在同一文件或已导入且对文档生成器可见的文件中。
适用场景
- 在 Dart 代码中编写或更新文档注释（///）。
- 检查失效的文档链接、引用或宏。
- 为发布到 pub.dev 准备包。
限制与不应使用的场景（Abstention Guardrails）
在以下情况不要应用本技能或重构文档注释：
- 说明性伪代码与非 Dart 代码围栏：注释包含伪代码、非 Dart 语言标识符（例如 yaml、json、bash、text），或有意设计为无法作为有效 Dart 编译的抽象概念片段。
- 生成代码：由工具生成的文件（例如 .g.dart、.mocks.dart、*.freezed.dart），其中注释是合成生成的。
- 外部 Markdown 超链接：方括号文本后跟链接目标（例如 External Guide），这是标准 Markdown 超链接语法，而非未解析的 Dart 文档引用。