Dart构造函数优质文档注释示例？以PQButton组件为例

对于要求所有公开成员加文档注释的Lint规则，PQButton这类组件的构造函数注释不用重复每个字段的基础含义（字段本身的注释可以覆盖），核心要讲清楚组件的定位和构造的关键特性/参数补充信息。

完整注释示例 #

/// 项目统一风格的交互按钮组件
class PQButton extends StatelessWidget {
  /// 创建一个可配置的PQButton实例
  /// 
  /// 使用const构造可提升性能，适用于无需动态更新的场景。
  /// 必填参数[text]为按钮显示的文本内容，其余参数提供默认值可快速使用品牌风格。
  const PQButton({
    super.key,
    required this.text,
    this.backgroundColor = brandYellow,
    this.textColor = brandBlack,
    this.textStyle = const TextStyle(
      color: brandBlack,
    ),
    this.onPressed,
  });

  /// 按钮点击后的回调方法，为空时按钮处于禁用状态
  final VoidCallback? onPressed;

  /// 按钮上显示的文本内容
  final String text;

  /// 按钮背景色，默认使用品牌黄色[brandYellow]
  final Color backgroundColor;

  /// 按钮文本颜色，默认使用品牌黑色[brandBlack]
  final Color textColor;

  /// 按钮文本样式，默认已配置品牌黑色字体，可覆盖调整
  final TextStyle textStyle;
}

注释逻辑说明 #

1. 类注释：直接点明组件的定位，让其他开发者一眼知道这个组件的用途
2. 构造函数注释：
   • 说明构造的基本作用
   • 补充特殊特性：比如这里的const构造，提一下性能优势
   • 重点提示必填参数和默认值的意义：比如text是必填的核心内容，其他参数用品牌默认值减少配置成本
3. 字段注释：针对每个字段补充具体含义，尤其是默认值对应的品牌规范、可选参数的状态（比如onPressed为空时按钮禁用）

这样既满足Lint规则要求，又能让注释真正有用，不会沦为无效的重复内容。

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