Doc

Code Documentation with LLMs

Use Cases for LLM-Powered Documentation

1. Generate Docstrings
Transform undocumented functions into fully documented ones:

**Before**
def process(data, threshold=0.5):
    return [x for x in data if x > threshold]

**After (LLM-generated)**
def process(data: list[float], threshold: float = 0.5) -> list[float]:
    """
    Filter numeric data by threshold.

    Args:
        data: List of numeric values to filter.
        threshold: Minimum value for inclusion (default: 0.5).

    Returns:
        List of values exceeding the threshold.

    Example:
        >>> process([0.1, 0.6, 0.3, 0.9], 0.5)
        [0.6, 0.9]
    """
    return [x for x in data if x > threshold]

2. Explain Complex Code
Make legacy or unfamiliar code understandable:

Prompt: "Explain this code in plain English, then add inline comments"

Input: complex_algorithm.py
Output: Step-by-step explanation + commented version

3. Generate README Files
Create comprehensive project documentation:
- Project overview and purpose
- Installation instructions
- Usage examples
- API reference summary
- Contributing guidelines

4. API Documentation
Auto-generate OpenAPI specs and usage examples from code.

Prompting Techniques

Documentation Style Control

Add Google-style docstrings to all functions in this Python module.
Include:
- Brief description
- Args with types and descriptions
- Returns with type and description
- Raises for exceptions
- Example usage where helpful

Explanation Levels
| Level | Prompt Addition | Audience |
|-------|-----------------|----------|
| Beginner | "Explain like I'm new to coding" | Juniors |
| Standard | "Explain what this code does" | Developers |
| Expert | "Analyze the algorithm complexity and design decisions" | Seniors |

Tools and Integrations

IDE Extensions
| Tool | IDE | Features |
|------|-----|----------|
| GitHub Copilot | VSCode, JetBrains | Inline suggestions |
| Cursor | Cursor IDE | Full codebase context |
| Codeium | Multiple | Free alternative |
| Continue | VSCode | Open source |

CLI Tools

**Generate docs for a file**
llm-docs generate --style google --file main.py

**Explain a function**
cat complex_function.py | llm "explain this code"

Best Practices

Do
- ✅ Review and edit generated docs
- ✅ Specify documentation style (Google, NumPy, Sphinx)
- ✅ Include examples in your prompt
- ✅ Generate incrementally (file by file)

Avoid
- ❌ Blindly accepting generated documentation
- ❌ Using for security-critical documentation without review
- ❌ Exposing proprietary code to public APIs

Example Workflow

import openai

def document_function(code: str, style: str = "google") -> str:
    """Generate documentation for a code snippet."""
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{
            "role": "user",
            "content": f"Add {style}-style docstrings to this Python code:

{code}"
        }]
    )
    return response.choices[0].message.content