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

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

Fork 0

Files

Zhongwei Li 6bdf233c6b Initial commit

2025-11-30 09:05:49 +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