When Documenting Code - Use Doc Generator

Overview

This skill provides automated, comprehensive documentation generation for codebases. It analyzes code structure, generates API documentation, creates README files, adds inline comments, and produces architecture diagrams using evidence-based documentation patterns.

MCP Requirements

This skill operates using Claude Code's built-in tools only. No additional MCP servers required.

Core Capabilities

1. Code Analysis: Extract APIs, functions, classes, types, and dependencies
2. API Documentation: Generate OpenAPI, JSDoc, TypeDoc, and Python docstrings
3. README Generation: Create comprehensive project documentation
4. Inline Comments: Add missing documentation with context-aware comments
5. Diagram Generation: Produce architecture and flow diagrams (Graphviz, Mermaid)

SPARC Methodology: Documentation Generation

Phase 1: SPECIFICATION - Analyze Documentation Requirements

Objective: Understand the codebase structure and documentation needs

Actions:

1. Scan project structure and identify file types
2. Detect programming languages and frameworks
3. Identify existing documentation (README, API docs, comments)
4. Analyze documentation gaps and missing coverage
5. Determine documentation standards (JSDoc, TSDoc, Python docstrings)

Deliverables:

• Project structure analysis
• Documentation gap report
• Recommended documentation strategy
• Style guide selection

Agent: code-analyzer

Example Analysis:

Project: express-api-server
Languages: JavaScript (TypeScript), 85% | JSON 10% | Markdown 5%
Frameworks: Express.js, Jest
Current Documentation:
  - README.md: Exists (outdated, 3 months old)
  - API Docs: None
  - Inline Comments: 12% coverage
  - Type Definitions: 45% coverage

Gaps Identified:
  - ❌ No API documentation (12 endpoints undocumented)
  - ❌ Missing installation instructions
  - ❌ No architecture diagrams
  - ⚠️  Low inline comment coverage
  - ✅ Package.json well-documented

Recommended Strategy:
  1. Generate OpenAPI 3.0 spec for REST API
  2. Add JSDoc comments to all public functions
  3. Create comprehensive README with badges
  4. Generate architecture diagram (system overview)
  5. Add usage examples for main features

Phase 2: PSEUDOCODE - Design Documentation Structure

Objective: Plan documentation hierarchy and templates

Actions:

1. Design documentation structure (README, API, guides)
2. Define comment style and conventions
3. Create templates for each documentation type
4. Plan diagram types and structure
5. Define metadata and frontmatter standards

Deliverables:

• Documentation structure outline
• Template designs for each type
• Comment convention guide
• Diagram specifications

Example Structure:

Documentation Hierarchy:

docs/
├── README.md                 # Project overview
├── INSTALLATION.md          # Setup guide
├── API.md                   # API reference
├── ARCHITECTURE.md          # System design
├── CONTRIBUTING.md          # Contribution guide
├── diagrams/
│   ├── system-overview.svg  # High-level architecture
│   ├── data-flow.svg        # Data flow diagram
│   └── api-endpoints.svg    # API structure
└── examples/
    ├── basic-usage.md
    └── advanced-features.md

Comment Standards:
- JSDoc for all exported functions
- TypeDoc for TypeScript interfaces
- File header with purpose and author
- Inline comments for complex logic only

API Documentation:
- OpenAPI 3.0 specification
- Example requests/responses
- Error code documentation
- Authentication guide

Phase 3: ARCHITECTURE - Define Generation Pipeline

Objective: Design the documentation generation workflow

Actions:

1. Define code parsing strategy (AST, regex, static analysis)
2. Design template engine for documentation generation
3. Plan diagram generation pipeline (Graphviz/Mermaid)
4. Define validation and quality checks
5. Create update and versioning strategy

Deliverables:

• Documentation generation pipeline
• Parser and extractor design
• Template rendering engine
• Validation rules

Pipeline Architecture:

┌─────────────────┐
│  Source Code    │
│  Repository     │
└────────┬────────┘
         │
         ▼
┌─────────────────────────┐
│  Code Analyzer          │
│  - AST Parsing          │
│  - Extract Functions    │
│  - Extract Types        │
│  - Detect Patterns      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Documentation Engine   │
│  ├─ API Generator       │
│  ├─ README Generator    │
│  ├─ Comment Generator   │
│  └─ Diagram Generator   │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Template Renderer      │
│  - Mustache/Handlebars  │
│  - Markdown Formatting  │
│  - Syntax Highlighting  │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Validator              │
│  - Link Checking        │
│  - Spelling             │
│  - Completeness         │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Output                 │
│  - docs/                │
│  - Inline Comments      │
│  - Generated Diagrams   │
└─────────────────────────┘

Phase 4: REFINEMENT - Generate and Validate Documentation

Objective: Execute documentation generation with quality checks

Actions:

1. Parse source code and extract documentation targets
2. Generate API documentation from code signatures
3. Create README from templates and project metadata
4. Add inline comments to undocumented code
5. Generate architecture and flow diagrams
6. Validate completeness and accuracy
7. Check links and references
8. Format and style according to standards

Deliverables:

• Complete API documentation
• Comprehensive README
• Inline code comments
• Architecture diagrams
• Validation report

Generation Examples:

Before (Undocumented Function):

function calculateDiscount(price, customerType, quantity) {
  const baseDiscount = customerType === 'premium' ? 0.15 : 0.05;
  const volumeDiscount = quantity > 100 ? 0.1 : quantity > 50 ? 0.05 : 0;
  return price * (1 - baseDiscount - volumeDiscount);
}

After (With JSDoc):

/**
 * Calculates the final price after applying customer and volume discounts
 *
 * @param {number} price - The original price before discounts
 * @param {('standard'|'premium')} customerType - Customer tier level
 * @param {number} quantity - Number of items purchased
 * @returns {number} The discounted price
 *
 * @example
 * // Premium customer buying 60 items at $100 each
 * calculateDiscount(100, 'premium', 60);
 * // Returns: 80 (15% customer + 5% volume discount)
 *
 * @see {@link https://docs.example.com/pricing|Pricing Documentation}
 */
function calculateDiscount(price, customerType, quantity) {
  // Premium customers receive 15% base discount, standard customers 5%
  const baseDiscount = customerType === 'premium' ? 0.15 : 0.05;

  // Volume discounts: 10% for 100+, 5% for 50+, 0% otherwise
  const volumeDiscount = quantity > 100 ? 0.1 : quantity > 50 ? 0.05 : 0;

  return price * (1 - baseDiscount - volumeDiscount);
}

API Documentation Generation:

# Generated OpenAPI 3.0 Specification
openapi: 3.0.0
info:
  title: E-commerce API
  version: 1.0.0
  description: REST API for e-commerce platform with pricing and inventory

paths:
  /api/v1/products/{id}/price:
    get:
      summary: Calculate product price with discounts
      description: Returns the final price after applying customer tier and volume discounts
      operationId: calculateProductPrice
      tags:
        - Pricing
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Product ID
        - name: quantity
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
          description: Quantity to purchase
        - name: customerType
          in: query
          required: false
          schema:
            type: string
            enum: [standard, premium]
            default: standard
          description: Customer tier level
      responses:
        '200':
          description: Price calculated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  originalPrice:
                    type: number
                    example: 100.00
                  discountedPrice:
                    type: number
                    example: 80.00
                  discountsApplied:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          enum: [customer, volume]
                        percentage:
                          type: number
                          example: 0.15
        '404':
          description: Product not found

README Generation:

# E-commerce API Server

[![Build Status](https://img.shields.io/travis/org/repo.svg)](https://travis-ci.org/org/repo)
[![Coverage](https://img.shields.io/codecov/c/github/org/repo.svg)](https://codecov.io/gh/org/repo)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

> Production-ready REST API for e-commerce platform with advanced pricing, inventory management, and order processing.

## Features

- ✅ Dynamic pricing with customer tiers and volume discounts
- ✅ Real-time inventory tracking
- ✅ Order processing and fulfillment
- ✅ JWT authentication with role-based access
- ✅ Rate limiting and security middleware
- ✅ Comprehensive API documentation (OpenAPI 3.0)

## Quick Start

### Prerequisites

- Node.js >= 18.0.0
- PostgreSQL >= 14.0
- Redis >= 7.0 (for caching)

### Installation

```bash
# Clone repository
git clone https://github.com/org/ecommerce-api.git
cd ecommerce-api

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your database credentials

# Run migrations
npm run migrate

# Start server
npm start

Usage

// Example: Calculate price with discounts
const response = await fetch(
  'http://localhost:3000/api/v1/products/prod-123/price?quantity=60&customerType=premium'
);
const { discountedPrice } = await response.json();
console.log(`Final price: $${discountedPrice}`);

API Documentation

Full API documentation available at:

• Interactive Docs: http://localhost:3000/api-docs (Swagger UI)
• OpenAPI Spec: docs/API.md

Key Endpoints

Method	Endpoint	Description
GET	/api/v1/products	List all products
GET	/api/v1/products/{id}	Get product details
GET	/api/v1/products/{id}/price	Calculate price with discounts
POST	/api/v1/orders	Create new order
GET	/api/v1/orders/{id}	Get order status

Architecture

See ARCHITECTURE.md for detailed system design.

Configuration

Variable	Description	Default
PORT	Server port	3000
DATABASE_URL	PostgreSQL connection	-
REDIS_URL	Redis connection	-
JWT_SECRET	Authentication secret	-

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run integration tests
npm run test:integration

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

MIT © 2025 Your Organization

### Phase 5: COMPLETION - Integrate and Maintain Documentation

**Objective**: Ensure documentation stays synchronized with code

**Actions**:
1. Integrate documentation into build pipeline
2. Set up automated documentation updates
3. Configure pre-commit hooks for comment validation
4. Establish documentation review process
5. Create documentation maintenance schedule

**Deliverables**:
- CI/CD integration
- Git hooks for documentation
- Maintenance schedule
- Documentation metrics dashboard

**Integration Strategy**:
```yaml
# .github/workflows/docs.yml
name: Documentation

on:
  push:
    branches: [main, develop]
  pull_request:

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Generate API documentation
        run: npm run docs:api

      - name: Generate diagrams
        run: npm run docs:diagrams

      - name: Validate documentation
        run: npm run docs:validate

      - name: Check comment coverage
        run: npm run docs:coverage

      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

Pre-commit Hook:

#!/bin/bash
# .git/hooks/pre-commit

echo "Checking documentation coverage..."

# Check for undocumented functions
undocumented=$(npm run --silent docs:check-coverage)

if [ $? -ne 0 ]; then
  echo "❌ Documentation coverage below threshold"
  echo "$undocumented"
  echo ""
  echo "Please add documentation to new functions before committing."
  exit 1
fi

echo "✅ Documentation coverage acceptable"

Usage Patterns

Basic Documentation Generation

# Generate all documentation
/doc-generate

# Generate specific documentation type
/doc-api          # API documentation only
/doc-readme       # README generation only
/doc-inline       # Add inline comments only
/doc-diagrams     # Generate diagrams only

Advanced Usage

# Generate with specific output format
npx claude-flow docs generate --format openapi --output docs/api.yml

# Generate for specific files
npx claude-flow docs generate --files "src/**/*.js" --type jsdoc

# Generate with custom templates
npx claude-flow docs generate --template custom-readme.hbs

# Update existing documentation
npx claude-flow docs update --incremental

# Validate documentation completeness
npx claude-flow docs validate --min-coverage 80

Documentation Standards

Comment Style Guide

JavaScript/TypeScript (JSDoc):

/**
 * Brief description (one sentence, under 100 chars)
 *
 * Detailed description explaining the purpose, behavior, and any
 * important considerations. This can span multiple lines.
 *
 * @param {Type} paramName - Description of parameter
 * @param {Type} [optionalParam=defaultValue] - Optional parameter
 * @returns {Type} Description of return value
 * @throws {ErrorType} When error occurs
 *
 * @example
 * // Example usage
 * const result = functionName(arg1, arg2);
 *
 * @see {@link RelatedFunction}
 * @since 1.0.0
 * @deprecated Use newFunction instead
 */

Python (Google Style):

def function_name(param1: str, param2: int = 0) -> bool:
    """Brief description (one sentence).

    Detailed description explaining the purpose and behavior.
    Can span multiple lines with proper formatting.

    Args:
        param1: Description of first parameter
        param2: Description of optional parameter (default: 0)

    Returns:
        Description of return value

    Raises:
        ValueError: When invalid input provided
        RuntimeError: When operation fails

    Example:
        >>> result = function_name("test", 5)
        >>> print(result)
        True

    Note:
        Important information or limitations
    """

README Template Structure

# Project Title

> Brief description (one sentence tagline)

[Badges: Build, Coverage, License, Version]

## Features

- Key feature 1
- Key feature 2
- Key feature 3

## Quick Start

### Prerequisites
### Installation
### Basic Usage

## Documentation

- [API Reference](docs/API.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Contributing](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)

## Examples

### Basic Example
### Advanced Example

## Configuration

## Testing

## Deployment

## Support

## License

Quality Metrics

Documentation Coverage Goals:

• Public API functions: 100% documented
• Internal functions: 80% documented
• Complex algorithms: 100% with inline comments
• Type definitions: 100% documented
• Examples: At least 1 per major feature

Validation Checks:

• ✅ All public functions have JSDoc/docstrings
• ✅ All parameters documented with types
• ✅ Return values documented
• ✅ Examples provided for complex functions
• ✅ Links valid and accessible
• ✅ No spelling errors
• ✅ Consistent formatting

Troubleshooting

Common Issues

Issue: Generated docs missing some functions

• Solution: Check function export syntax, ensure export keyword used

Issue: Diagrams not rendering

• Solution: Install Graphviz: brew install graphviz or apt install graphviz

Issue: JSDoc comments not showing in IDE

• Solution: Configure TypeScript to include JSDoc in tsconfig.json

Issue: README badges not updating

• Solution: Check CI/CD pipeline, verify badge URLs

Best Practices

1. Write documentation as you code - Don't defer to later
2. Keep comments concise - Explain "why" not "what"
3. Use examples liberally - Show, don't just tell
4. Update diagrams regularly - Keep architecture docs current
5. Validate before committing - Use pre-commit hooks
6. Review documentation in PRs - Treat docs as first-class code
7. Version documentation - Tag docs with release versions
8. Link related concepts - Create documentation graph
9. Avoid redundancy - Single source of truth
10. Test examples - Ensure code samples actually work

Integration with Other Skills

• code-review-assistant: Validates documentation in PRs
• tdd-workflow: Generates test documentation
• api-design-first: Creates API docs from specs
• refactoring-assistant: Updates docs during refactoring

References

• JSDoc Documentation
• TypeDoc Documentation
• OpenAPI Specification
• Google Python Style Guide
• Markdown Guide
• Graphviz Documentation

---

Version: 1.0.0 Last Updated: 2025-10-30 Maintainer: Base Template Generator Status: Production Ready

---

Core Principles

1. Documentation as Code

Documentation should be treated as a first-class citizen in the codebase, not an afterthought.

In practice:

• Write documentation at the same time as code, not after
• Use the same version control, review processes, and CI/CD pipelines for documentation
• Keep documentation close to the code it describes (inline comments, README in same directory)
• Validate documentation in pre-commit hooks and CI pipelines
• Measure documentation coverage like test coverage (aim for 80%+ public API coverage)

2. Progressive Disclosure

Structure documentation hierarchically so readers can find exactly what they need without cognitive overload.

In practice:

• Start with high-level overviews (README), drill down to details (API docs, implementation notes)
• Use clear navigation: table of contents, cross-references, breadcrumbs
• Provide examples before diving into parameter lists
• Layer complexity: basic usage first, advanced features later
• Link related concepts instead of duplicating information

3. Single Source of Truth

Avoid documentation duplication and drift by maintaining one authoritative source.

In practice:

• Generate API documentation from code signatures, not manual typing
• Use type definitions and JSDoc as the source, render multiple formats from it
• Reference existing documentation instead of copying
• Automate documentation updates when code changes
• Use canonical URLs and permalinks for stability

---

Anti-Patterns

Anti-Pattern	Problem	Solution
Documentation Debt	Writing code first, deferring documentation "for later" results in outdated or missing docs	Use pre-commit hooks to enforce documentation coverage. Treat undocumented code as incomplete. Block PRs that reduce documentation coverage below threshold.
Copy-Paste Documentation	Duplicating information across multiple files leads to inconsistency when one copy is updated but others are forgotten	Establish a single source of truth (e.g., OpenAPI spec, JSDoc). Generate all documentation from that source. Use links/references instead of duplication.
Over-Documenting the Obvious	Cluttering code with comments that restate what the code already says clearly wastes reader time and adds maintenance burden	Focus on "why" not "what". Only document complex algorithms, edge cases, and non-obvious behavior. Let self-documenting code (clear naming, simple logic) speak for itself.
Stale Examples	Hardcoded examples in documentation break when APIs change, eroding trust in all documentation	Extract examples from automated tests. Run documentation examples in CI to ensure they work. Use live code snippets that pull from actual working code.
Missing Context	Documentation that assumes reader knowledge creates barriers for new contributors and users	Provide prerequisites, background, and "why this matters" sections. Link to foundational concepts. Include architecture diagrams showing how components relate.
No Accessibility	Documentation lacking alt text, contrast, or reading order excludes users relying on screen readers or assistive tech	Follow WCAG 2.1 AA standards. Add alt text to all diagrams. Use semantic HTML. Test with screen readers. Provide text alternatives for visual information.

---

Conclusion

Comprehensive documentation is not a luxury - it is a force multiplier for engineering teams. Well-documented code accelerates onboarding, reduces support burden, prevents knowledge silos, and enables confident refactoring. By treating documentation as code, applying progressive disclosure, and maintaining a single source of truth, teams transform documentation from a chore into a strategic asset.

The doc-generator skill automates the mechanical work of documentation creation, freeing developers to focus on the creative aspects: explaining design decisions, providing meaningful examples, and capturing the "why" behind the code. When combined with CI/CD integration and quality gates, automated documentation becomes self-healing infrastructure that stays synchronized with the codebase.

Remember: the best documentation is the documentation that exists, is accurate, and is discoverable. Start with automation, enforce with tooling, and maintain with discipline. Your future self - and your teammates - will thank you.