documentation

---
name: documentation
description: Generate and analyze code documentation, comments, README files, API docs, and ensure documentation quality and accuracy
license: Apache-2.0
---

# Documentation

Expert documentation generator and analyzer. Creates comprehensive documentation, verifies comment accuracy, and ensures long-term code maintainability through quality documentation.

## Overview

This skill helps you generate high-quality documentation and analyze existing documentation for accuracy, completeness, and long-term value. It protects codebases from "comment rot" by ensuring every comment adds genuine value and remains accurate as code evolves.

## Capabilities

### 1. Generate Documentation

Create comprehensive documentation for your code:

**What it generates:**
- JSDoc/docstrings for functions and classes
- README files with usage examples
- API documentation
- Inline comments explaining complex logic
- CHANGELOG entries

**Usage:**
```
"Generate documentation for this function"
"Add JSDoc comments to this module"
"Create README for this project"
"Добавь документацию"
```

**Example:**
```javascript
// Before
async function fetchUserData(userId, options) {
  const response = await fetch(`/api/users/${userId}`, options);
  if (!response.ok) throw new Error('Failed');
  return response.json();
}

// After (Generated by skill)
/**
 * Fetches user data from the API.
 *
 * @param {string} userId - The unique identifier of the user
 * @param {RequestInit} [options] - Optional fetch configuration
 * @returns {Promise<User>} Promise resolving to user data
 * @throws {Error} When the API request fails or user is not found
 *
 * @example
 * const user = await fetchUserData('123');
 * console.log(user.name);
 *
 * @example
 * const user = await fetchUserData('123', {
 *   headers: { Authorization: 'Bearer token' }
 * });
 */
async function fetchUserData(userId, options) {
  const response = await fetch(`/api/users/${userId}`, options);
  if (!response.ok) throw new Error('Failed');
  return response.json();
}
```

### 2. Analyze Comment Quality

Review existing comments for accuracy and value:

**What it checks:**
- Comment accuracy vs. actual code
- Completeness of documentation
- Comment rot and technical debt
- Misleading or outdated comments

**Usage:**
```
"Check if comments are accurate"
"Review documentation quality"
"Analyze comments for technical debt"
"Проверь комментарии"
```

**Output format:**
```
## Comment Analysis

### Critical Issues (Must Fix)
1. **Inaccurate comment in API client**
   - File: src/api/client.ts:45
   - Issue: Comment says "returns User" but returns UserDTO
   - Suggestion: Update to "returns UserDTO (not full User object)"

### Improvement Opportunities
1. **Missing parameter documentation**
   - File: src/utils/helpers.ts:12
   - Current: No documentation for complex function
   - Suggestion: Add JSDoc explaining parameters and return value

### Recommended Removals
1. **Redundant comment**
   - File: src/index.ts:8
   - Comment: "Initialize the app" on `initApp()` call
   - Rationale: Just restates the obvious

### Positive Findings
✓ Well-documented complex algorithm in src/search.ts
✓ Good use of examples in JSDoc
```

### 3. Generate README

Create comprehensive README files:

**Usage:**
```
"Create README for this project"
"Generate project documentation"
"Update README"
```

**README includes:**
- Project title and description
- Installation instructions
- Usage examples
- API reference
- Configuration options
- Contributing guidelines
- License information

### 4. Generate CHANGELOG

Create or update CHANGELOG files:

**Usage:**
```
"Generate CHANGELOG"
"Update changelog for new version"
"Create release notes"
```

**Follows Keep a Changelog format:**
```markdown
## [1.2.0] - 2025-02-22

### Added
- New authentication provider support
- Rate limiting middleware

### Changed
- Improved error messages
- Updated dependencies

### Fixed
- Memory leak in cache cleanup
- Race condition in user update
```

## Documentation Guidelines

### What Makes Good Comments

1. **Explain Why, Not What**
   ```javascript
   // Bad: Explains obvious code
   // Increment counter
   counter++;

   // Good: Explains reasoning
   // Retry counter - reset after 5 attempts to prevent infinite loops
   counter++;
   ```

2. **Document Complex Logic**
   ```javascript
   // Binary search with custom comparator for date ranges
   // We use bisect_right to find insertion point after existing range
   const index = _.sortedIndexBy(ranges, newRange, r => r.startDate);
   ```

3. **Include Examples**
   ```javascript
   /**
    * Formats currency with locale support
    * @example
    * formatCurrency(1234.5, 'en-US') // "$1,234.50"
    * formatCurrency(1234.5, 'de-DE') // "1.234,50 €"
    */
   ```

4. **Document Assumptions**
   ```javascript
   // Assumes input is already validated by middleware
   // Do NOT call this function with untrusted input
   function processUserData(data) { ... }
   ```

### Documentation Anti-Patterns

**Don't:**
- State the obvious: `// Increment i` on `i++`
- Leave outdated comments after refactoring
- Write comments that contradict the code
- Use comments to explain poor code (fix the code instead)
- Include TODOs without issue references

**Do:**
- Keep comments current with code changes
- Remove comments that are no longer relevant
- Use clear, concise language
- Document non-obvious behavior
- Explain business logic decisions

## Language-Specific Documentation

### JavaScript/TypeScript (JSDoc)

```typescript
/**
 * Calculates discount amount based on price and percentage.
 *
 * @param price - Original price in dollars
 * @param discountPercent - Discount percentage (0-100)
 * @returns Final price after discount
 * @throws {RangeError} When discountPercent is outside 0-100
 *
 * @example
 * calculateDiscount(100, 20) // 80
 * calculateDiscount(50, 0)   // 50
 */
function calculateDiscount(price: number, discountPercent: number): number {
  if (discountPercent < 0 || discountPercent > 100) {
    throw new RangeError('Discount must be between 0 and 100');
  }
  return price * (1 - discountPercent / 100);
}
```

### Python (Docstrings)

```python
def calculate_discount(price: float, discount_percent: float) -> float:
    """
    Calculate the final price after applying a discount.

    Args:
        price: Original price in dollars
        discount_percent: Discount percentage (0-100)

    Returns:
        Final price after discount

    Raises:
        ValueError: If discount_percent is outside 0-100 range

    Examples:
        >>> calculate_discount(100, 20)
        80.0
        >>> calculate_discount(50, 0)
        50.0
    """
    if not 0 <= discount_percent <= 100:
        raise ValueError('Discount must be between 0 and 100')
    return price * (1 - discount_percent / 100)
```

### Rust

```rust
/// Calculates the discounted price.
///
/// # Arguments
///
/// * `price` - Original price
/// * `discount_percent` - Discount percentage (0-100)
///
/// # Returns
///
/// Final price after discount
///
/// # Errors
///
/// Returns `Err` if discount_percent is outside 0-100 range
///
/// # Examples
///
/// ```
/// let price = calculate_discount(100.0, 20.0)?;
/// assert_eq!(price, 80.0);
/// ```
pub fn calculate_discount(price: f64, discount_percent: f64) -> Result<f64, String> {
    if discount_percent < 0.0 || discount_percent > 100.0 {
        return Err("Discount must be between 0 and 100".to_string());
    }
    Ok(price * (1.0 - discount_percent / 100.0))
}
```

## Analysis Categories

When analyzing comments, the skill checks:

### 1. Factual Accuracy
- Function signatures match documented parameters
- Described behavior aligns with actual logic
- Referenced types and functions exist
- Edge cases mentioned are handled

### 2. Completeness
- Critical assumptions documented
- Non-obvious side effects mentioned
- Error conditions described
- Complex algorithms explained

### 3. Long-term Value
- Comments explain "why" not "what"
- Written for future maintainers
- Not referencing temporary states
- Will remain accurate as code evolves

### 4. Misleading Elements
- Ambiguous language
- Outdated references
- False assumptions
- Unaddressed TODOs

## Usage Patterns

### Pattern 1: Document New Code
```
User: "Add documentation to this new module"
→ Skill generates comprehensive JSDoc
```

### Pattern 2: Review Before PR
```
User: "Check if comments are accurate before I create PR"
→ Skill analyzes and reports issues
```

### Pattern 3: Cleanup Legacy Code
```
User: "Review comments for technical debt"
→ Skill identifies outdated/misleading comments
```

### Pattern 4: Generate Project Docs
```
User: "Create README for this project"
→ Skill generates comprehensive README
```

## Integration with Other Skills

This skill works great with:
- **code-simplifier**: Simplify code before documenting
- **feature-dev**: Document features as they're built
- **code-review**: Check documentation in PRs
- **test-generation**: Document test cases and examples

## Troubleshooting

### "Documentation seems redundant"
**Issue**: Generated docs restate obvious code

**Solution**: 
- The skill focuses on "why" and non-obvious aspects
- Review and remove any redundant comments manually
- Remember: comments should add value

### "Comments are too verbose"
**Issue**: Documentation feels excessive

**Solution**:
- Good documentation balances completeness with brevity
- Remove obvious explanations
- Keep critical context and "why" explanations

### "Outdated documentation"
**Issue**: Code changed but comments didn't

**Solution**:
- Run comment analysis regularly
- Include documentation checks in code review
- Use the skill to identify outdated comments

## Best Practices

### When to Document
- Public APIs and exported functions
- Complex algorithms or business logic
- Non-obvious side effects
- Error conditions and edge cases
- Configuration options

### When NOT to Document
- Self-evident code
- Implementation details that may change
- Obvious getters/setters
- Test code (unless complex)

### Documentation Maintenance
1. Update comments when changing code
2. Remove outdated documentation
3. Review docs during code review
4. Keep examples working and current

## Original Source

Converted from: https://github.com/anthropics/claude-plugins-official/tree/main/plugins/pr-review-toolkit (comment-analyzer agent)
License: See LICENSE file in original repository (MIT)