mcpField
D
dart-use-doc-examples

dart-use-doc-examples

github.com/flutter开发3.1k6.8k 次安装2 天前更新
代码仓库

关于 dart-use-doc-examples

面向编写 Dart API 文档示例的技能指南，介绍如何从独立文件插入代码示例，并按区域提取或隐藏辅助代码。它还说明路径解析规则及分析和生成文档的验证方法。

主要功能

  1. 01使用 {@example} 插入外部代码示例
  2. 02通过 region 提取示例片段
  3. 03用 #hide 隐藏辅助代码行
  4. 04说明包根路径与相对路径解析
  5. 05验证示例并检查 Dartdoc 输出

适用场景

  1. 01为 API 文档添加可分析的多行示例
  2. 02从包含完整设置的文件展示精简代码片段
  3. 03排查示例文件路径或 region 解析问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/flutter/agent-plugins --skill dart-use-doc-examples

安装后在 Claude Code 中输入/dart-use-doc-examples确认已加载。

详细介绍

在 Dartdoc 中使用示例

目录

编写需要多行代码示例的文档时，通常应将这些示例提取到独立的 .dart 文件中，再使用 {@example} 指令插入，而不是直接写在 /// 注释中。这样可以确保示例能够通过分析、检查并执行。

1. {@example} 指令

{@example} 指令会解析外部文件，并将其转换为生成文档中的带围栏 Markdown 代码块。

语法： {@example <path>[#<region>] [lang=LANGUAGE] [indent=keep|strip]}

  • <path>：文件路径。以 / 开头时，从软件包根目录解析；否则相对于当前文件。
  • lang：Markdown 代码围栏使用的语言。根据文件扩展名自动检测（例如 dart），也可以显式指定（例如 lang=text）。
  • indent：strip（默认值）会尽可能移除代码块共有的前导缩进。

错误示例（内联 Markdown）：

/// Makes a client service request to the backend.
///
/// ```dart
/// final client = Client();
/// client.send();
/// ```

正确示例（插入外部文件）：

/// Makes a client service request to the backend.
///
/// {@example /example/client_request.dart}

2. 使用区域

外部示例文件通常包含导入语句、设置代码或 void main() 包装代码，而这些内容可能无需显示在文档中。你可以在 {@example} 指令路径后附加 #<region>，并在目标文件中使用 #region 和 #endregion 注释包围要提取的代码块。

Dart 代码（例如，/example/client.dart）：

import 'package:http/http.dart';

void main() {
  // #region request_snippet
  final client = Client();
  client.send();
  // #endregion request_snippet
}

Dartdoc 用法：

/// Connects the client to the server and sends a request.
///
/// {@example /example/client.dart#request_snippet}

3. 隐藏设置代码

如果提取的区域中有某一行代码是编译器或分析器检查所必需的，但对文档读者而言无关紧要（或会造成干扰），请在该行末尾附加 #hide。

Dart 代码：

final mockServer = startServer(); // #hide
final data = await fetch(mockServer.url);

在生成的文档中，只有 final data = await fetch(mockServer.url); 会显示。带有 #hide 的行会被完全删除。

4. 标记过滤规则

使用 #hide、#region 和 #endregion 标记时，必须遵守以下两项技术约束：

  • 必须指定区域： 只有在指定区域后缀（例如 {@example file.dart#region_name}）时，才会处理并移除这些标记。如果插入整个文件而没有区域后缀，文件会按源文件中的原样嵌入，包括 // #hide 等标记文本。
  • 与格式无关： 标记系统完全与格式无关。Dartdoc 只会运行正则表达式来移除包含标记字符串的行，因此它在非 Dart 文件中也会以相同方式工作（例如，在 YAML 注释 # #region 或 HTML 注释 `` 中）。

5. 放置位置和路径解析

{@example} 指令是块级指令，必须单独放在一行，并以 /// 开头。其内部的 <path> 解析器遵循严格的 URI 引用规则：

  • 包根路径（/）：以斜杠开头的路径会自动直接解析到 Dart 包的根目录。当目标文件位于较深的目录中时，请使用此方式。
    • 示例： {@example /test/data/sample.txt} 会精确映射到 <package_root>/test/data/sample.txt。
  • 相对路径：不以斜杠开头的路径会相对于包含文档注释的文件所在目录解析。
    • 示例： {@example ../utils/demo.dart}
  • 边界限制： 使用 .. 片段向上遍历完全可行，但 dartdoc 会原生地将目录遍历限制在包根目录内（绝不会越出包目录）。
  • 不支持网络 URL： 严格不支持绝对 URI（例如以 https:// 开头的 URI）。示例文件必须原生地位于本地文件系统中的某个位置。
  • 分隔符和编码： 由于 dartdoc 会将路径作为 URI 解析，因此文件夹分隔符必须始终使用正斜杠（/），即使在 Windows 上也是如此。根据 URI 引用规则，可以原生地包含 URI 编码字符（例如表示空格的 %20）。

6. 验证

注入示例后：

  1. 对示例文件运行 dart analyze，确保隐藏的设置代码能够编译。
  2. （可选）运行 dart doc，验证 dartdoc 是否成功解析该指令，且没有出现“Failed to read file”或“missing region”警告。

评论

支持 Markdown