如何在Dart中为工厂方法的参数添加文档注释？

在Dart中，给工厂方法的单个参数添加可被IDE识别的文档注释，完全可以达到和构造函数参数注释一致的体验，以下是具体实现方式：

1. 使用标准的参数注释格式 #

直接在工厂方法的文档注释块中，通过[参数名]: 注释内容的格式单独说明每个参数，Dart的文档工具（dartdoc）和主流IDE（VS Code、Android Studio）都会识别并在用户使用时展示参数提示。

示例代码：

/// 创建一款主风格的自定义按钮
/// 
/// [text]: 按钮上显示的核心文本，不能为空字符串
/// [onPressed]: 按钮点击时触发的回调逻辑，传null时按钮会处于不可点击状态
/// [icon]: 可选的前置图标，不传则不显示
factory CustomButton.primary({
  required String text,
  required VoidCallback? onPressed,
  IconData? icon,
}) {
  return CustomButton._(
    text: text,
    onPressed: onPressed ?? () {},
    style: ButtonStyles.primary,
    icon: icon,
  );
}

2. 与私有构造函数注释联动 #

如果工厂方法是封装了私有构造函数，可以同步参数注释的逻辑，让私有构造的注释作为兜底，同时在工厂方法中补充该场景下的特殊说明。

示例代码：

class CustomButton {
  final String text;
  final VoidCallback onPressed;
  final ButtonStyle style;
  final IconData? icon;

  /// 私有构造函数，定义按钮的核心属性
  /// 
  /// [text]: 按钮显示文本
  /// [onPressed]: 点击回调
  /// [style]: 按钮样式配置
  /// [icon]: 可选图标
  CustomButton._({
    required this.text,
    required this.onPressed,
    required this.style,
    this.icon,
  });

  /// 创建主风格按钮（默认带圆角效果）
  /// 
  /// [text]: 按钮文本，支持传入LocalizedString实现国际化
  /// [onPressed]: 点击回调，为null时按钮自动置灰
  factory CustomButton.primary({
    required String text,
    required VoidCallback? onPressed,
    IconData? icon,
  }) {
    return CustomButton._(
      text: text,
      onPressed: onPressed ?? () {},
      style: ButtonStyles.primary.copyWith(borderRadius: BorderRadius.circular(8)),
      icon: icon,
    );
  }
}

3. 确保文档生成配置正确 #

在包的pubspec.yaml中添加dartdoc到开发依赖，这样生成的官方文档会完整展示所有参数注释，进一步提升包的易用性：

dev_dependencies:
  dartdoc: ^6.0.1

按上述方式编写注释后，用户在使用你的工厂方法时，输入参数的过程中就能像使用Flutter内置Widget一样，看到单个参数的专属注释提示，完全不会降低包的易用性。

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