系统地管理多语言的 docstring/注释,维护高质量的文档。
Generates and updates multi-language docstrings following language-specific standards with quality checks.
/plugin marketplace add wasabeef/claude-code-cookbook/plugin install cook-zh-cn@claude-code-cookbook系统地管理多语言的 docstring/注释,维护高质量的文档。
# 自动检测语言并执行
「为没有 docstring 的类和函数添加注释,并更新不符合标准的注释」
# 指定语言执行
/update-doc-string --lang python
「按照 PEP 257 规范更新 Python 文件的 docstring」
# 特定目录的文档整理
「为 src/components/ 下的函数添加 JSDoc」
--lang <en|zh-cn> : 文档记述语言 (默认:从现有注释自动判定,无则为 en)--style <风格> : 指定文档风格 (有语言特定的默认值)--marker <true|false> : 是否添加 Claude 标记 (默认:true)# 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 标记」
目标元素 (通用):
Python (PEP 257):
# 中文版 (默认)
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):
/**
* 显示用户个人资料的组件。(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:
// CalculateTotal 计算商品列表的总金额。(30-60 个字符)
//
// 将每个商品的价格和数量相乘,返回含税总额。
// 空切片时返回 0.0。(50-200 个字符)
//
// Generated by Claude 🤖
func CalculateTotal(items []Item) float64 {
Rust:
/// 计算商品列表的总金额。(30-60 个字符)
///
/// 将每个商品的价格和数量相乘,返回含税总额。
/// 空向量时返回 0.0。(50-200 个字符)
///
/// Generated by Claude 🤖
pub fn calculate_total(items: &[Item]) -> f64 {
Dart (DartDoc):
/// 显示用户个人资料的 Widget。(30-60 个字符)
///
/// 垂直排列头像图片、用户名和状态信息,
/// 点击时跳转到个人资料详情页面。(50-200 个字符)
///
/// Generated by Claude 🤖
class UserProfileWidget extends StatelessWidget {
应保留的重要信息:
See also:、@see、参照: 等TODO:、FIXME:、XXX: 格式Note:、Warning:、注意: 等Example:、例:、# Examples 等# 语言特定默认设置
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: "///"
🔴 绝对禁止事项:
执行和验证:
# 记录执行结果
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 个"
完成判定: 满足以下所有条件时成功
部分成功: 以下情况
失败: 以下情况
# 分析整个项目 (自动判定语言)
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"
/update-doc-stringGerencia sistematicamente docstrings/comentários multilíngues e mantém documentação de alta qualidade.
/update-doc-stringSystematically manage multilingual docstrings/comments and maintain high-quality documentation.