203 lines
5.4 KiB
Markdown
203 lines
5.4 KiB
Markdown
## 更新 Dart 文档
|
||
|
||
系统地管理 Dart 文件的 DartDoc 注释，维护高质量的中文文档。
|
||
|
||
### 使用方法
|
||
|
||
```bash
|
||
# 同时执行新增和更新
|
||
「为没有 DartDoc 注释的类添加注释，并更新不符合标准的注释」
|
||
|
||
# 确认 PR 的更改文件
|
||
「确认 PR #4308 中更改的文件是否有 Claude 标记」
|
||
|
||
# 特定目录的文档整理
|
||
「为 packages/app/lib/ui/screen/ 下的 Widget 类添加 DartDoc」
|
||
|
||
# 不带标记执行
|
||
/update-dart-doc --marker false
|
||
「改进现有项目的 DartDoc(不添加 Claude 标记)」
|
||
```
|
||
|
||
### 选项
|
||
|
||
- `--marker <true|false>` : 是否添加 Claude 标记 (默认：true)
|
||
|
||
### 基本示例
|
||
|
||
```bash
|
||
# 1. 分析目标文件
|
||
find . -name "*.dart" -not -path "*/.*" | grep -v "_test.dart" | grep -v "_vrt.dart"
|
||
「识别缺少 DartDoc 的类 (注释行数为 0 或少于 30 个字符)」
|
||
|
||
# 2. 添加文档
|
||
「为识别的类添加包含必要元素的 DartDoc 注释」
|
||
|
||
# 3. 确认标记
|
||
「确认所有添加或更新的 DartDoc 都有 Claude 标记」
|
||
```
|
||
|
||
### 执行步骤
|
||
|
||
#### 1. 目标元素的优先级
|
||
|
||
1. 🔴 **最优先**: 没有 DartDoc 注释的元素 (注释行数为 0)
|
||
2. 🟡 **次优先**: 不符合标准的元素 (少于 30 个字符或缺少必要元素)
|
||
3. 🟢 **确认对象**: 没有 Claude 标记的现有注释
|
||
|
||
**目标元素**：
|
||
|
||
- Class(所有类定义)
|
||
- Enum(枚举类型)
|
||
- Extension(扩展方法)
|
||
- 重要函数 (顶级函数，可选)
|
||
|
||
#### 2. DartDoc 编写规则
|
||
|
||
**基本结构**：
|
||
|
||
```dart
|
||
/// {元素的概要说明}(30-60 个字符，必需)
|
||
///
|
||
/// {详细说明}(必须包含角色、使用场景、注意事项，50-200 个字符)
|
||
///
|
||
/// Generated by Claude 🤖
|
||
@注解 // 不更改现有注解
|
||
class 类名 {
|
||
```
|
||
|
||
**文体风格**：
|
||
|
||
- 礼貌用语 (敬语体)："显示内容"、"管理状态的类"
|
||
- 使用中文标点："。"、"，"
|
||
- 中文与半角英数字之间加半角空格
|
||
- 技术术语使用英文："Authentication 状态"
|
||
- 每行不超过 80 个字符
|
||
|
||
#### 3. 按类别的描述示例
|
||
|
||
**状态管理类 (Riverpod)**：
|
||
|
||
```dart
|
||
/// 管理水平滑动手势禁用状态的 State。
|
||
///
|
||
/// 在需要禁用水平滑动的特定画面或操作中使用。
|
||
/// 例如，轮播显示或特定输入时。
|
||
///
|
||
/// Generated by Claude 🤖
|
||
@Riverpod(keepAlive: true, dependencies: [])
|
||
class HorizontalDragGestureIgnoreState extends _$HorizontalDragGestureIgnoreState {
|
||
```
|
||
|
||
**Widget 类**：
|
||
|
||
```dart
|
||
/// 显示用户个人资料的 Widget。
|
||
///
|
||
/// 垂直排列头像图片、用户名和状态信息，
|
||
/// 点击时跳转到个人资料详情页面。
|
||
///
|
||
/// Generated by Claude 🤖
|
||
class UserProfileWidget extends HookConsumerWidget {
|
||
```
|
||
|
||
#### 4. 现有内容保留规则
|
||
|
||
1. **现有注释符合标准时**: 保持原样 (不新增)
|
||
- 标准：30 个字符以上且包含必要元素 (概要、详细、标记)
|
||
2. **现有注释不符合标准时**: 完全替换 (不重复)
|
||
3. **没有现有注释时**: 添加新注释
|
||
|
||
**应保留的重要信息**：
|
||
|
||
- URL 和链接：以 `See also:` 开头的引用
|
||
- TODO 注释：`TODO(user_name):` 格式
|
||
- 注意事项：`注意:` 或 `Warning:` 等警告
|
||
- 使用示例：以 `例:` 或 `Example:` 开头的代码
|
||
- 技术约束：性能或限制的描述
|
||
|
||
### Claude 标记管理
|
||
|
||
```bash
|
||
# 标记格式
|
||
/// 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`) 添加不符合字符数标准的注释
|
||
|
||
**静态分析和提交**：
|
||
|
||
```bash
|
||
# 记录执行结果
|
||
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 🤖"
|
||
```
|
||
|
||
### 执行成功标准
|
||
|
||
1. **完成判定**: 满足以下所有条件时成功
|
||
- `melos analyze` 显示 PASSED
|
||
- 错误数为 0
|
||
- 添加和更新的注释都符合标准
|
||
|
||
2. **部分成功**: 以下情况
|
||
- 错误数少于 5 个
|
||
- 90% 以上符合标准
|
||
|
||
3. **失败**: 以下情况
|
||
- `melos analyze` 显示 FAILED
|
||
- 错误数为 5 个或以上
|