## 更新文档字符串

系统地管理多语言的 docstring/注释，维护高质量的文档。

### 使用方法

```bash
# 自动检测语言并执行
「为没有 docstring 的类和函数添加注释，并更新不符合标准的注释」

# 指定语言执行
/update-doc-string --lang python
「按照 PEP 257 规范更新 Python 文件的 docstring」

# 特定目录的文档整理
「为 src/components/ 下的函数添加 JSDoc」
```

### 选项

- `--lang <en|zh-cn>` : 文档记述语言 (默认：从现有注释自动判定，无则为 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-cn，否则为 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-cn"
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-cn
「按照语言特定的最佳实践更新这个项目的 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"
```