Update Doc String

---
description: 'Manage multilingual docstrings and comments. Trigger with "update docstrings", "manage comments", "add documentation comments", "update JSDoc".'
allowed-tools:
  - Read
  - Edit
  - Grep
  - Glob
---

# Manage multilingual docstrings and comments

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