Dart 中如何引用复用已有方法的文档字符串

首先需要明确一个容易混淆的认知：

• Dart 本身没有内置“通过普通注解直接拉取其他元素文档、自动拼接成当前元素文档”的原生语法，你之前见到的@方法名DocString形式的写法，是其他编程语言文档体系的实现逻辑，直接搬到Dart环境里完全不生效——官方文档生成工具dartdoc只会收集紧邻代码声明的///注释文本，不会自动读取普通注解关联的注释内容完成合并。

要实现“减少重复文档编写、统一保障文档准确性与可维护性”的目标，用以下两类官方支持的正规方案即可，完全能达到你预期的最终文档呈现效果：

方案1：通过dartdoc内置的宏（Macro）机制实现通用文档片段复用 #

这是匹配你需求的最直接实现方式，支持把公共文档片段抽离后，在任意位置灵活引用，生成文档时自动完成内容拼接，不需要手动重复粘贴相同文本。

• 第一步：集中定义可复用的公共文档宏块。一般把所有公共片段写在一个私有辅助类的文档注释里，用{@template 宏的唯一ID}和{@endtemplate}把公共片段包裹起来：

  /// {@template method1_common_doc}
  /// This is a doc string for this method.
  /// {@endtemplate}
  class _PrivateDocTemplates {}
  

• 第二步：在需要使用这段公共文档的位置，直接通过{@macro 宏的唯一ID}插入引用，后续补充当前元素独有的文档内容即可：

  /// {@macro method1_common_doc}
  ///
  /// method 2 doc string added to method1's here.
  void method2() {}
  

最终生成正式文档时，dartdoc会自动把宏对应的公共内容替换到引用位置，和你预期的最终呈现效果完全一致。后续如果需要调整公共文档内容，只需要修改一次宏的定义，所有引用该宏的位置都会同步更新，不需要逐处调整修改。

方案2：利用dartdoc原生的文档继承能力 #

如果你的复用场景是子类重写父类方法、实现接口方法的场景，连抽公共片段的步骤都可以省略——dartdoc本身支持自动继承父级的文档内容：

• 父类、接口方法的通用说明（比如入参规则、通用异常说明、核心功能定义）只需要在父级位置编写一次
• 子类重写方法的注释里，只需要补充当前实现特有的说明内容，不需要重复编写的段落直接留空
• 生成文档时，工具会自动把父级的对应文档内容补全到子类方法的文档里，完成自动拼接。

额外注意：如果想靠自定义手写的Dart注解实现自动拉取、拼接文档的效果，需要额外开发专属的dartdoc插件做注解解析、内容拼接逻辑，开发和维护成本远高于直接使用官方提供的宏和文档继承能力，无特殊需求不建议采用这种方式。

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