管理多語言 docstring 和註解

系統地管理多語言的 docstring/注釋，維護高質量的文檔。

使用方法

bash
# 自動檢測語言並執行
「為没有 docstring 的類和函數添加注釋，並更新不符合標準的注釋」

# 指定語言執行
/update-doc-string --lang python
「按照 PEP 257 規範更新 Python 文件的 docstring」

# 特定目錄的文檔整理
「為 src/components/ 下的函數添加 JSDoc」

選項

• --lang <en|zh-tw> : 文檔記述語言 (默認：從現有注釋自動判定，無則為 en)
• --style <風格> : 指定文檔風格 (有語言特定的默認值)
• --marker <true|false> : 是否添加 Claude 標記 (默認：true)

基本示例

bash
# 1. 分析目標文件 (自動檢測編程語言)
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.dart" -o -name "*.go" -o -name "*.rs" \) | grep -v test
「識別缺少 docstring 的元素 (注釋行數為 0 或少于 30 個字符)」

# 2. 添加文檔 (自動判定語言)
「為識別的元素添加包含語言特定必要元素的 docstring」
# → 如果現有注釋中有中文則用中文，否則用英文

# 3. 添加文檔 (明確指定英文)
/update-doc-string --lang en
「Add docstrings with required elements to the identified elements」

# 4. 確認標記
「確認所有添加或更新的 docstring 都有 Claude 標記」

執行步骤

1. 目標元素的優先級

1. 🔴 最優先: 没有 docstring/注釋的元素 (注釋行數為 0)
2. 🟡 次優先: 不符合標準的元素 (少于 30 個字符或缺少必要元素)
3. 🟢 確認對象: 没有 Claude 標記的現有注釋

目標元素 (通用)：

• Class/類定義
• Function/函數和方法
• Module/模塊 (Python, Go)
• Enum/枚舉類型
• Interface/接口 (TypeScript, Go)

2. 語言特定編寫規則

Python (PEP 257)：

python
# 中文版 (默認)
def calculate_total(items: List[Item]) -> float:
    """計算商品列表的總金额。(30-60 個字符)

    將每個商品的價格和數量相乘，返回含税總额。
    空列表時返回 0.0。(50-200 個字符)

    Args:
        items: 要計算的商品列表

    Returns:
        含税總金额

    Generated by Claude 🤖
    """

# 英文版 (--lang en)
def calculate_total(items: List[Item]) -> float:
    """Calculate the total amount for a list of items. (30-60 chars)

    Multiplies the price and quantity of each item and returns
    the total with tax. Returns 0.0 for empty lists. (50-200 chars)

    Args:
        items: List of items to calculate

    Returns:
        Total amount with tax

    Generated by Claude 🤖
    """

JavaScript/TypeScript (JSDoc)：

javascript
/**
 * 顯示用戶個人資料的組件。(30-60 個字符)
 *
 * 顯示头像圖片、用戶名和狀態資訊，
 * 點擊時跳轉到個人資料詳情页面。(50-200 個字符)
 *
 * @param {Object} props - 組件属性
 * @param {string} props.userId - 用戶 ID
 * @param {boolean} [props.showStatus=true] - 狀態顯示標誌
 * @returns {JSX.Element} 渲染的組件
 *
 * @generated by Claude 🤖
 */
const UserProfile = ({ userId, showStatus = true }) => {

Go：

go
// CalculateTotal 計算商品列表的總金额。(30-60 個字符)
//
// 將每個商品的價格和數量相乘，返回含税總额。
// 空切片時返回 0.0。(50-200 個字符)
//
// Generated by Claude 🤖
func CalculateTotal(items []Item) float64 {

Rust：

rust
/// 計算商品列表的總金额。(30-60 個字符)
///
/// 將每個商品的價格和數量相乘，返回含税總额。
/// 空向量時返回 0.0。(50-200 個字符)
///
/// Generated by Claude 🤖
pub fn calculate_total(items: &[Item]) -> f64 {

Dart (DartDoc)：

dart
/// 顯示用戶個人資料的 Widget。(30-60 個字符)
///
/// 垂直排列头像圖片、用戶名和狀態資訊，
/// 點擊時跳轉到個人資料詳情页面。(50-200 個字符)
///
/// Generated by Claude 🤖
class UserProfileWidget extends StatelessWidget {

3. 現有內容保留規則

1. 現有注釋符合標準時: 保持原樣 (不新增)

• 標準：30 個字符以上且包含必要元素 (概要、詳细、標記)

1. 現有注釋不符合標準時: 完全替換 (不重復)
2. 没有現有注釋時: 添加新注釋

應保留的重要資訊：

• URL 和鏈接：See also:、@see、參照: 等
• TODO 注釋：TODO:、FIXME:、XXX: 格式
• 注意事項：Note:、Warning:、注意: 等
• 使用示例：Example:、例:、# Examples 等
• 現有的參數和返回值說明

語言特定設置

yaml
# 語言特定默認設置
languages:
  python:
    style: "google" # google, numpy, sphinx
    indent: 4
    quotes: '"""'

  javascript:
    style: "jsdoc"
    indent: 2
    prefix: "/**"
    suffix: "*/"

  typescript:
    style: "tsdoc"
    indent: 2
    prefix: "/**"
    suffix: "*/"

  go:
    style: "godoc"
    indent: 0
    prefix: "//"

  rust:
    style: "rustdoc"
    indent: 0
    prefix: "///"

  dart:
    style: "dartdoc"
    indent: 0
    prefix: "///"

質量檢查清單

• ✅ 字符數: 严格遵守概要 30-60 個字符、詳细 50-200 個字符
• ✅ 必要元素: 必须包含概要、詳细說明、Claude 標記三個元素
• ✅ 完整性: 記載角色、使用場景、注意事項
• ✅ 語言規範: 遵循各語言的官方風格指南
• ✅ 異常: 錯誤和異常的說明 (如適用)
• ✅ 準確性: 分析實現，仅記載基于事實的描述

注意事項

🔴 绝對禁止事項：

• ❌ 更改文檔注釋以外的代碼
• ❌ 推測實現细节 (仅記載事實)
• ❌ 违反語言規範的格式
• ❌ 刪除或更改現有的類型注解
• ❌ 與現有注釋重復
• ❌ 為測試文件添加不符合字符數標準的注釋

執行和驗證：

bash
# 記錄執行結果
ADDED_COMMENTS=0
UPDATED_COMMENTS=0
ERRORS=0

# 從現有注釋自動判定語言
# 檢測中文字符則為 zh-tw，否則為 en
DOC_LANGUAGE="en"  # 默認
if grep -r '[一-龥]' --include="*.py" --include="*.js" --include="*.ts" --include="*.dart" --include="*.go" --include="*.rs" . 2>/dev/null | head -n 1; then
  DOC_LANGUAGE="zh-tw"
fi

# 自動檢測編程語言並執行靜態分析
if [ -f "*.py" ]; then
  pylint --disable=all --enable=missing-docstring .
elif [ -f "*.js" ] || [ -f "*.ts" ]; then
  eslint . --rule 'jsdoc/require-jsdoc: error'
elif [ -f "*.go" ]; then
  golint ./...
elif [ -f "*.rs" ]; then
  cargo doc --no-deps
elif [ -f "*.dart" ]; then
  melos analyze
fi

if [ $? -ne 0 ]; then
  echo "🔴 錯誤：靜態分析失败"
  exit 1
fi

# 輸出執行摘要
echo "📊 執行結果："
echo "- 文檔語言：$DOC_LANGUAGE"
echo "- 添加的注釋：$ADDED_COMMENTS 條"
echo "- 更新的注釋：$UPDATED_COMMENTS 條"
echo "- 錯誤數：$ERRORS 個"

執行成功標準

1. 完成判定: 满足以下所有條件時成功

• 語言特定的靜態分析顯示 PASSED
• 錯誤數為 0
• 添加和更新的注釋都符合標準

1. 部分成功: 以下情况

• 錯誤數少于 5 個
• 90% 以上符合標準

1. 失败: 以下情况

• 靜態分析顯示 FAILED
• 錯誤數為 5 個或以上

與 Claude 配合

bash
# 分析整個項目 (自動判定語言)
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \)
/update-doc-string
「按照語言特定的最佳實践更新這個項目的 docstring」
# → 如果現有注釋中有中文則用 ja，否則用 en

# 明確指定英文文檔
/update-doc-string --lang en
"Update docstrings following language-specific best practices"

# 明確指定中文文檔
/update-doc-string --lang zh-tw
「按照語言特定的最佳實践更新這個項目的 docstring」

# 不带標記執行 (自動判定語言)
/update-doc-string --marker false
"Improve existing docstrings without adding Claude markers"

# 英文文檔，不带標記
/update-doc-string --lang en --marker false
"Improve existing docstrings without adding Claude markers"