系統地管理多語言的 docstring/注釋,維護高質量的文檔。
Systematically manages multi-language docstrings and comments to maintain high-quality documentation.
/plugin marketplace add wasabeef/claude-code-cookbook/plugin install cook-zh-tw@claude-code-cookbook系統地管理多語言的 docstring/注釋,維護高質量的文檔。
# 自動檢測語言並執行
「為没有 docstring 的類和函數添加注釋,並更新不符合標準的注釋」
# 指定語言執行
/update-doc-string --lang python
「按照 PEP 257 規範更新 Python 文件的 docstring」
# 特定目錄的文檔整理
「為 src/components/ 下的函數添加 JSDoc」
--lang <en|zh-tw> : 文檔記述語言 (默認:從現有注釋自動判定,無則為 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-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 個"
完成判定: 满足以下所有條件時成功
部分成功: 以下情况
失败: 以下情况
# 分析整個項目 (自動判定語言)
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"
/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.