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 個或以上
|