doc
**Code Documentation with LLMs**
**Use Cases for LLM-Powered Documentation**
**1. Generate Docstrings**
Transform undocumented functions into fully documented ones:
```python
**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**
```bash
**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**
```python
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
```