gh-wasabeef-claude-code-cookbook-plugins-zh-cn/commands/update-dart-doc.md at master

zhongwei/gh-wasabeef-claude-code-cookbook-plugins-zh-cn

Fork 0

Files

Zhongwei Li a64cee7b84 Initial commit

2025-11-30 09:05:46 +08:00

5.4 KiB

Raw Permalink Blame History

更新 Dart 文档

系统地管理 Dart 文件的 DartDoc 注释，维护高质量的中文文档。

使用方法

# 同时执行新增和更新
「为没有 DartDoc 注释的类添加注释，并更新不符合标准的注释」

# 确认 PR 的更改文件
「确认 PR #4308 中更改的文件是否有 Claude 标记」

# 特定目录的文档整理
「为 packages/app/lib/ui/screen/ 下的 Widget 类添加 DartDoc」

# 不带标记执行
/update-dart-doc --marker false
「改进现有项目的 DartDoc(不添加 Claude 标记)」

选项

--marker <true|false> : 是否添加 Claude 标记 (默认：true)

基本示例

# 1. 分析目标文件
find . -name "*.dart" -not -path "*/.*" | grep -v "_test.dart" | grep -v "_vrt.dart"
「识别缺少 DartDoc 的类 (注释行数为 0 或少于 30 个字符)」

# 2. 添加文档
「为识别的类添加包含必要元素的 DartDoc 注释」

# 3. 确认标记
「确认所有添加或更新的 DartDoc 都有 Claude 标记」

执行步骤

1. 目标元素的优先级

🔴 最优先: 没有 DartDoc 注释的元素 (注释行数为 0)
🟡 次优先: 不符合标准的元素 (少于 30 个字符或缺少必要元素)
🟢 确认对象: 没有 Claude 标记的现有注释

目标元素：

Class(所有类定义)
Enum(枚举类型)
Extension(扩展方法)
重要函数 (顶级函数，可选)

2. DartDoc 编写规则

基本结构：

/// {元素的概要说明}(30-60 个字符，必需)
///
/// {详细说明}(必须包含角色、使用场景、注意事项，50-200 个字符)
///
/// Generated by Claude 🤖
@注解  // 不更改现有注解
class 类名 {

文体风格：

礼貌用语 (敬语体)："显示内容"、"管理状态的类"
使用中文标点："。"、"，"
中文与半角英数字之间加半角空格
技术术语使用英文："Authentication 状态"
每行不超过 80 个字符

3. 按类别的描述示例

状态管理类 (Riverpod)：

/// 管理水平滑动手势禁用状态的 State。
///
/// 在需要禁用水平滑动的特定画面或操作中使用。
/// 例如，轮播显示或特定输入时。
///
/// Generated by Claude 🤖
@Riverpod(keepAlive: true, dependencies: [])
class HorizontalDragGestureIgnoreState extends _$HorizontalDragGestureIgnoreState {

Widget 类：

/// 显示用户个人资料的 Widget。
///
/// 垂直排列头像图片、用户名和状态信息，
/// 点击时跳转到个人资料详情页面。
///
/// Generated by Claude 🤖
class UserProfileWidget extends HookConsumerWidget {

4. 现有内容保留规则

现有注释符合标准时: 保持原样 (不新增)
- 标准：30 个字符以上且包含必要元素 (概要、详细、标记)
现有注释不符合标准时: 完全替换 (不重复)
没有现有注释时: 添加新注释

应保留的重要信息：

URL 和链接：以 See also: 开头的引用
TODO 注释：TODO(user_name): 格式
注意事项：注意: 或 Warning: 等警告
使用示例：以 例: 或 Example: 开头的代码
技术约束：性能或限制的描述

Claude 标记管理

# 标记格式
/// Generated by Claude 🤖

# 在 PR 更改文件中确认标记
gh pr diff 4308 --name-only | grep "\.dart$" | xargs grep -l "Generated by Claude"
「为没有标记的文件添加标记」

质量检查清单

✅ 字符数: 严格遵守概要 30-60 个字符、详细 50-200 个字符
✅ 必要元素: 必须包含概要、详细说明、Claude 标记三个元素
✅ 完整性: 记载角色、使用场景、注意事项
✅ 一致性: 统一使用礼貌用语 (敬语体)
✅ 格式: 中文与英文之间加半角空格
✅ 准确性: 分析实现，仅记载基于事实的描述
✅ 结构: 保留注解，注释放在上方
✅ 长度: 每行不超过 80 个字符
✅ 标记: Claude 的更改必须添加标记

注意事项

🔴 绝对禁止事项：

❌ 更改文档注释以外的代码
❌ 推测实现细节 (仅记载事实)
❌ 中英文不自然的混用
❌ 删除或更改现有注解
❌ 与现有注释重复
❌ 为测试文件 (*_test.dart) 添加不符合字符数标准的注释
❌ 为 VRT 文件 (*_vrt.dart) 添加不符合字符数标准的注释

静态分析和提交：

# 记录执行结果
ADDED_COMMENTS=0
UPDATED_COMMENTS=0
ERRORS=0

# 更改后确认
melos analyze
if [ $? -ne 0 ]; then
  echo "🔴 错误：静态分析失败"
  exit 1
fi

# 输出执行摘要
echo "📊 执行结果："
echo "- 添加的注释：$ADDED_COMMENTS 条"
echo "- 更新的注释：$UPDATED_COMMENTS 条"
echo "- 错误数：$ERRORS 个"

# 提交示例
git commit -m "docs: 添加和更新 DartDoc 注释

- 为不符合标准的类、enum、extension 添加 DartDoc
- 更新少于 30 个字符的注释以符合标准
- 统一添加 Claude 标记

执行结果：
- 添加：$ADDED_COMMENTS 条
- 更新：$UPDATED_COMMENTS 条

Generated by Claude 🤖"

执行成功标准

完成判定: 满足以下所有条件时成功
- melos analyze 显示 PASSED
- 错误数为 0
- 添加和更新的注释都符合标准
部分成功: 以下情况
- 错误数少于 5 个
- 90% 以上符合标准
失败: 以下情况
- melos analyze 显示 FAILED
- 错误数为 5 个或以上

5.4 KiB Raw Permalink Blame History Unescape Escape