在 Dartdoc 中注入可分析的外部代码示例并按…

当 Dart API 文档需要多行代码示例，并希望示例来自可被分析、lint 和执行的独立文件时使用。

适用场景

解决思路

1. 当文档需要多行代码示例时，将示例提取为独立的 `.dart` 文件，并用 `{@example}` 指令注入，而不是直接写在 `///` 注释里；这样可确保示例能被分析、lint 和执行。
2. 使用 `{@example}` 指令解析外部文件，并在生成文档中将其解析为围栏 Markdown 代码块。
3. 指令语法为：`{@example <path>[#<region>] [lang=LANGUAGE] [indent=keep|strip]}`。
4. `<path>` 是文件路径：以 `/` 开头时从包根目录求值，否则相对于当前文件。
5. `lang` 是 Markdown 围栏语言：默认从文件扩展名自动检测（如 `dart`），也可显式指定（如 `lang=text`）。
6. `indent` 控制缩进：`strip` 是默认值，会积极移除代码块的共享前导缩进。
7. 用外部文件注入替代内联 Markdown：例如不要写内联 ```` ```dart ... ``` ````，而是在文档注释中写 `{@example /example/client_request.dart}`。
8. 使用 region 提取特定代码块：在 `{@example}` 路径后追加 `#<region>`，并在目标文件中用 `#region` 和 `#endregion` 注释包裹该代码块。
9. 在 Dart 示例文件中写 `// #region request_snippet` 和 `// #endregion request_snippet` 包裹要展示的代码，然后在 Dartdoc 中使用 `{@example /example/client.dart#request_snippet}`。
10. 隐藏必要但无关的 setup 代码：在需要被编译器/分析器保留但不展示给文档读者的行末追加 `#hide`。
11. 示例：写 `final mockServer = startServer(); // #hide`；生成文档只显示 `final data = await fetch(mockServer.url);`，带 `#hide` 的行被完全丢弃。
12. 遵守 Region Required 规则：只有指定 region 后缀（如 `{@example file.dart#region_name}`）时，`#hide`、`#region`、`#endregion` 标记才会被处理和剥离；若注入整个文件而无 region 后缀，文件会按源样嵌入，标记文本也会保留。
13. 利用格式无关性：标记系统用正则剥离包含标记字符串的行，因此同样适用于非 Dart 文件，例如 YAML 注释 `# #region` 或 HTML 注释 `<!-- #region -->`。
14. 将 `{@example}` 作为块级指令使用：它必须出现在单独一行，并以 `///` 前缀。
15. 路径解析遵循 URI 引用规则：以 `/` 开头的包根路径直接解析到 Dart 包根目录，适合目标文件很深时；例如 `{@example /test/data/sample.txt}` 精确映射到 `<package_root>/test/data/sample.txt`。
16. 相对路径：不以 `/` 开头的路径相对于包含该文档注释的文件所在目录解析；例如 `{@example ../utils/demo.dart}`。
17. 边界限制：允许用 `..` 向上遍历，但 dartdoc 会在包根目录停止，不会逃出包。
18. 不支持网络 URL：以 `https://` 等开头的绝对 URI 严格不支持；示例文件必须位于本地文件系统。
19. 路径分隔符与编码：由于按 URI 解析，即使 Windows 也必须使用正斜杠 `/` 作为文件夹分隔符；可包含 URI 编码字符，如 `%20` 表示空格。
20. 注入示例后运行 `dart analyze` 分析示例文件，确保隐藏的 setup 代码可编译。
21. 可选运行 `dart doc`，验证 dartdoc 成功解析指令，且没有 Failed to read file 或 missing region 警告。

适用边界 · 注意事项

• 当示例文件必须通过绝对 URI 或网络 URL（如 `https://`）引用时，不支持。
• 当使用非 Dartdoc 的文档系统，或不需要示例文件被分析、lint 和执行时，不适用。
• 当注入整个文件却不带 `#<region>` 后缀，却期望 `#hide`、`#region`、`#endregion` 被自动移除时，不适用；标记会原样保留。