管理多语言 docstring 和注释

系统地管理多语言的 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 个字符以上且包含必要元素 (概要、详细、标记)

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-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
• 添加和更新的注释都符合标准

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-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"