## 更新文檔字符串

系統地管理多語言的 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 個字符以上且包含必要元素 (概要、詳细、標記)
2. **現有注釋不符合標準時**: 完全替換 (不重復)
3. **没有現有注釋時**: 添加新注釋

**應保留的重要資訊**：

- 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
   - 添加和更新的注釋都符合標準

2. **部分成功**: 以下情况
   - 錯誤數少于 5 個
   - 90% 以上符合標準

3. **失败**: 以下情况
   - 靜態分析顯示 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"
```