Initial commit

2025-11-30 09:05:29 +08:00
commit 91fde12a8b
51 changed files with 11738 additions and 0 deletions
--- a/commands/update-doc-string.md
+++ b/commands/update-doc-string.md
@@ -0,0 +1,306 @@
+## Update Doc String
+
+Systematically manage multilingual docstrings/comments and maintain high-quality documentation.
+
+### Usage
+
+```bash
+# Run with automatic language detection
+"Please add docstrings to classes and functions without them, and update comments that don't meet standards"
+
+# Run with specified language
+/update-doc-string --lang python
+"Please update docstrings in Python files to comply with PEP 257"
+
+# Maintain documentation for specific directories
+"Please add JSDoc to functions under src/components/"
+```
+
+### Options
+
+- `--lang <language>` : Documentation language (default: en)
+- `--style <style>` : Specify documentation style (has language-specific defaults)
+- `--marker <true|false>` : Whether to add Claude markers (default: true)
+
+### Basic Examples
+
+```bash
+# 1. Analyze target files (programming language is auto-detected)
+find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.dart" -o -name "*.go" -o -name "*.rs" \) | grep -v test
+"Please identify elements with insufficient docstrings (0 comment lines or fewer than 30 characters)"
+
+# 2. Add documentation (uses English by default)
+"Please add docstrings containing language-specific required elements to the identified elements"
+# → Uses English for all documentation
+
+# 3. Add documentation (explicitly specify English)
+/update-doc-string --lang en
+"Add docstrings with required elements to the identified elements"
+
+# 4. Check markers
+"Please confirm that all added/updated docstrings have Claude markers"
+```
+
+### Execution Steps
+
+#### 1. Priority of Target Elements
+
+1. 🔴 **Highest Priority**: Elements without docstrings/comments (0 comment lines)
+2. 🟡 **Next Priority**: Elements not meeting standards (fewer than 30 characters or missing required elements)
+3. 🟢 **Verification Target**: Existing comments without Claude markers
+
+**Target Elements (Common Across Languages)**:
+
+- Class definitions
+- Functions/methods
+- Modules (Python, Go)
+- Enums
+- Interfaces (TypeScript, Go)
+
+#### 2. Language-Specific Documentation Rules
+
+**Python (PEP 257)**:
+
+```python
+# English version (default)
+def calculate_total(items: List[Item]) -> float:
+    """Calculate the total amount for a list of items. (30-60 characters)
+
+    Multiplies the price and quantity of each item and returns
+    the total with tax. Returns 0.0 for empty lists. (50-200 characters)
+
+    Args:
+        items: List of items to calculate
+
+    Returns:
+        Total amount with tax
+
+    Generated by Claude 🤖
+    """
+
+# English version (--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
+/**
+ * Component that displays a user profile. (30-60 characters)
+ *
+ * Displays avatar image, username, and status information,
+ * and navigates to the profile detail screen when clicked. (50-200 characters)
+ *
+ * @param {Object} props - Component properties
+ * @param {string} props.userId - User ID
+ * @param {boolean} [props.showStatus=true] - Status display flag
+ * @returns {JSX.Element} Rendered component
+ *
+ * @generated by Claude 🤖
+ */
+const UserProfile = ({ userId, showStatus = true }) => {
+```
+
+**Go**:
+
+```go
+// CalculateTotal calculates the total amount for a list of items. (30-60 characters)
+//
+// Multiplies the price and quantity of each item and returns
+// the total with tax. Returns 0.0 for empty slices. (50-200 characters)
+//
+// Generated by Claude 🤖
+func CalculateTotal(items []Item) float64 {
+```
+
+**Rust**:
+
+```rust
+/// Calculate the total amount for a list of items. (30-60 characters)
+///
+/// Multiplies the price and quantity of each item and returns
+/// the total with tax. Returns 0.0 for empty vectors. (50-200 characters)
+///
+/// Generated by Claude 🤖
+pub fn calculate_total(items: &[Item]) -> f64 {
+```
+
+**Dart (DartDoc)**:
+
+```dart
+/// Widget that displays a user profile. (30-60 characters)
+///
+/// Vertically arranges avatar image, username, and status information,
+/// and navigates to the profile detail screen when tapped. (50-200 characters)
+///
+/// Generated by Claude 🤖
+class UserProfileWidget extends StatelessWidget {
+```
+
+#### 3. Existing Content Retention Rules
+
+1. **If existing comments meet standards**: Keep as-is (do not add new ones)
+   - Standards: At least 30 characters and includes required elements (summary, details, marker)
+2. **If existing comments do not meet standards**: Completely replace (no duplication)
+3. **If no existing comments**: Add new comments
+
+**Important Information to Retain**:
+
+- URLs and links: `See also:`, `@see`, `References:` etc.
+- TODO comments: `TODO:`, `FIXME:`, `XXX:` format
+- Notes: `Note:`, `Warning:`, `Important:` etc.
+- Examples: `Example:`, `Usage:`, `# Examples` etc.
+- Existing parameter and return value descriptions
+
+### Language-Specific Settings
+
+```yaml
+# Language-specific default settings
+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: "///"
+```
+
+### Quality Checklist
+
+- ✅ **Character Count**: Strictly adhere to 30-60 characters for summary, 50-200 for details
+- ✅ **Required Elements**: Always include summary, detailed description, and Claude marker
+- ✅ **Completeness**: Describe role, usage context, and notes
+- ✅ **Language Conventions**: Comply with official style guides for each language
+- ✅ **Exceptions**: Explain errors and exceptions (when applicable)
+- ✅ **Accuracy**: Analyze implementation and only include fact-based descriptions
+
+### Notes
+
+**🔴 Strict Prohibitions**:
+
+- ❌ Code changes other than documentation comments
+- ❌ Speculation about implementation details (only facts)
+- ❌ Formats that violate language conventions
+- ❌ Deletion or modification of existing type annotations
+- ❌ Duplication with existing comments
+- ❌ Comments below character count standards in test files
+
+**Execution and Verification**:
+
+```bash
+# Record execution results
+ADDED_COMMENTS=0
+UPDATED_COMMENTS=0
+ERRORS=0
+
+# Auto-detect language from existing comments
+# If Japanese characters (hiragana, katakana, kanji) are detected, use ja; otherwise, use en
+DOC_LANGUAGE="en"  # Default
+if grep -E -r '[\u3040-\u309F\u30A0-\u30FF\u4E00-\u9FAF]' --include="*.py" --include="*.js" --include="*.ts" --include="*.dart" --include="*.go" --include="*.rs" . 2>/dev/null | head -n 1; then
+  DOC_LANGUAGE="ja"
+fi
+
+# Auto-detect programming language and perform static analysis
+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 "🔴 Error: Static analysis failed"
+  exit 1
+fi
+
+# Output execution summary
+echo "📊 Execution Results:"
+echo "- Documentation Language: $DOC_LANGUAGE"
+echo "- Added Comments: $ADDED_COMMENTS"
+echo "- Updated Comments: $UPDATED_COMMENTS"
+echo "- Errors: $ERRORS"
+```
+
+### Success Criteria
+
+1. **Completion Criteria**: Success when all of the following are met:
+   - Language-specific static analysis PASSED
+   - Error count is 0
+   - All added/updated comments meet standards
+
+2. **Partial Success**: In the following cases:
+   - Error count is less than 5
+   - More than 90% meet standards
+
+3. **Failure**: In the following cases:
+   - Static analysis FAILED
+   - Error count is 5 or more
+
+### Integration with Claude
+
+```bash
+# Analyze entire project (auto language detection)
+find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \)
+/update-doc-string
+"Update this project's docstrings following language-specific best practices"
+# → If existing comments contain Japanese, run with ja; otherwise, run with en
+
+# Explicitly run with English documentation
+/update-doc-string --lang en
+"Update docstrings following language-specific best practices"
+
+# Explicitly run with Japanese documentation
+/update-doc-string --lang ja
+"Update this project's docstrings following language-specific best practices"
+
+# Run without markers (auto language detection)
+/update-doc-string --marker false
+"Improve existing docstrings without adding Claude markers"
+
+# English documentation, no markers
+/update-doc-string --lang en --marker false
+"Improve existing docstrings without adding Claude markers"
+```