Dart不同文件中能否在某方法文档里引用另一方法的文档内容？

你在Flutter源码中看到的{@macro}语法是Dart官方文档生成工具dartdoc的专属模板指令，并非Dart语言层面的宏，它本身是支持跨文件文档内容复用的，你遇到的“不生效”问题通常是以下两个原因导致：

• 生效场景限制：{@macro}仅在执行dart doc命令生成静态API文档时才会被解析替换，Dart分析器目前不支持解析该指令，因此IDE的代码悬浮提示、补全预览里不会显示引用的宏内容，很多人会误以为它没有生效。
• 缺少前置模板定义：要使用{@macro}引用内容，需要先在源文档位置用{@template}和{@endtemplate}定义好命名模板，你看到的Flutter代码中flutter.widgets.editableText.keyboardType就是官方提前定义好的模板唯一标识。

正确使用步骤 #

1. 在源文档位置定义命名模板：

/// {@template your.custom.template.name}
/// 这里是你要复用的文档内容
/// 支持普通的dartdoc语法，比如引用类[SomeClass]、格式标记等
/// {@endtemplate}
void sourceFunction() {}

2. 在需要复用文档的位置引用模板：

/// {@macro your.custom.template.name}
void targetFunction() {}

3. 执行dart doc命令生成项目的API文档，打开生成的静态文档站点即可看到目标函数的文档位置已经自动填充了模板内的所有内容。

已知限制 #

• 目前Dart分析器暂不支持解析dartdoc的宏指令，因此IDE内无法预览跨文件引用的文档内容，仅生成的静态文档可见。
• 模板名称全局唯一，不能重复定义。

内容的提问来源于stack exchange，提问作者Ced