Initial commit

2025-11-30 09:05:46 +08:00
commit a64cee7b84
51 changed files with 11796 additions and 0 deletions
--- a/commands/update-doc-string.md
+++ b/commands/update-doc-string.md
@@ -0,0 +1,306 @@
+## 更新文档字符串
+
+系统地管理多语言的 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"
+```