Automated Documentation and Code Generation
Table of Contents
1. File Headers and Metadata
File headers provide essential context about source code ownership, licensing, and purpose.
1.1. License Headers
Standard Apache 2.0 header:
/**
* Copyright 2025 Jason Walsh
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*/
1.2. Auto-generated Headers
Headers can include metadata for build systems and generators:
# -*- coding: utf-8 -*-
"""
Module: data_processor.py
Auto-generated: 2025-12-22T10:30:00Z
Generator: CodeGen v2.1.0
"""
2. JSDoc Documentation
2.1. Syntax and Tags
JSDoc uses block comments with @ tags for comprehensive API documentation:
/**
* Calculates the total price with tax and discount.
*
* @param {number} price - The base price of the item
* @param {number} taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
* @param {number} [discount=0] - Optional discount percentage
* @returns {number} The final calculated price
* @throws {Error} When price or taxRate is negative
* @example
* calculateTotal(100, 0.08, 10)
* // returns 97.2
*/
function calculateTotal(price, taxRate, discount = 0) {
if (price < 0 || taxRate < 0) {
throw new Error('Price and tax rate must be non-negative');
}
return price * (1 + taxRate) * (1 - discount / 100);
}
2.2. Type Annotations
Modern JSDoc supports TypeScript-style type definitions:
/**
* @typedef {Object} User
* @property {string} id - Unique user identifier
* @property {string} email - User email address
* @property {string[]} roles - Array of user roles
* @property {Date} createdAt - Account creation timestamp
*/
/**
* @param {User} user - The user object
* @returns {boolean} True if user is admin
*/
function isAdmin(user) {
return user.roles.includes('admin');
}
3. Modern Documentation Tools
3.1. TypeDoc for TypeScript
TypeDoc generates HTML documentation from TypeScript source code:
/**
* Generic repository for database operations.
*
* @typeParam T - The entity type managed by this repository
*/
export class Repository<T extends { id: string }> {
/**
* Finds an entity by its unique identifier.
*
* @param id - The entity ID to search for
* @returns Promise resolving to the entity or null
*/
async findById(id: string): Promise<T | null> {
// Implementation
return null;
}
}
Configuration in typedoc.json:
{
"entryPoints": ["src/index.ts"],
"out": "docs",
"theme": "default",
"excludePrivate": true
}
3.2. Sphinx for Python
Sphinx uses reStructuredText and supports multiple output formats:
def process_data(items, threshold=0.5, normalize=True):
"""Process a collection of data items with optional normalization.
Args:
items (List[float]): Input data values to process
threshold (float, optional): Filtering threshold. Defaults to 0.5.
normalize (bool, optional): Apply normalization. Defaults to True.
Returns:
List[float]: Processed data values
Raises:
ValueError: If items list is empty
TypeError: If items contains non-numeric values
Example:
>>> process_data([1.0, 2.0, 3.0], threshold=1.5)
[2.0, 3.0]
"""
if not items:
raise ValueError("Items list cannot be empty")
filtered = [x for x in items if x >= threshold]
return [x / max(filtered) for x in filtered] if normalize else filtered
3.3. Rustdoc for Rust
Rustdoc uses markdown-flavored documentation comments:
/// A thread-safe cache with TTL support.
///
/// # Examples
///
/// ```
/// use mylib::Cache;
///
/// let cache = Cache::new(100);
/// cache.insert("key", "value", Duration::from_secs(60));
/// assert_eq!(cache.get("key"), Some("value"));
/// ```
///
/// # Panics
///
/// Panics if capacity is zero.
pub struct Cache<K, V> {
capacity: usize,
// fields...
}
impl<K, V> Cache<K, V> {
/// Creates a new cache with the specified capacity.
///
/// # Arguments
///
/// * `capacity` - Maximum number of items to store
pub fn new(capacity: usize) -> Self {
assert!(capacity > 0, "Capacity must be greater than zero");
Cache { capacity }
}
}
3.4. AI-Assisted Documentation (LLMs)
Using language models to generate documentation from code:
# Example using OpenAI API
import openai
def generate_docstring(function_code):
"""Generate docstring using LLM."""
prompt = f"""Generate a comprehensive Python docstring for this function:
{function_code}
Include Args, Returns, Raises, and Example sections."""
response = openai.ChatCompletion.create(
model="gpt-4",
messages=[{"role": "user", "content": prompt}]
)
return response.choices[0].message.content
4. Code Generation
4.1. AST-Based Generation
Using Abstract Syntax Trees to generate code:
import ast
def generate_test_skeleton(source_file):
"""Generate test stubs from source code using AST."""
with open(source_file) as f:
tree = ast.parse(f.read())
tests = []
for node in ast.walk(tree):
if isinstance(node, ast.FunctionDef):
test_name = f"test_{node.name}"
tests.append(f"""
def {test_name}():
\"\"\"Test for {node.name}.\"\"\"
# TODO: Implement test
pass
""")
return "\n".join(tests)
4.2. Template-Based Approaches
Using templates for consistent code generation:
from jinja2 import Template
crud_template = Template("""
class {{ model_name }}Repository:
def create(self, {{ model_var }}: {{ model_name }}) -> {{ model_name }}:
# Implementation
pass
def read(self, id: str) -> Optional[{{ model_name }}]:
# Implementation
pass
def update(self, {{ model_var }}: {{ model_name }}) -> {{ model_name }}:
# Implementation
pass
def delete(self, id: str) -> bool:
# Implementation
pass
""")
# Generate repository class
code = crud_template.render(model_name="User", model_var="user")
4.3. LLM Code Generation
Modern approach using language models for code generation:
def generate_boilerplate(description):
"""Generate code from natural language description."""
system_prompt = """You are a code generator. Generate clean,
well-documented code based on user requirements."""
# Example with Claude API
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-4-5-20251101",
max_tokens=2048,
messages=[{
"role": "user",
"content": f"Generate Python code: {description}"
}]
)
return message.content[0].text
# Usage
code = generate_boilerplate(
"Create a REST API endpoint for user authentication with JWT"
)
5. Google Closure Compiler Integration
The Closure Compiler uses JSDoc annotations for type checking and optimization:
/**
* @constructor
* @param {string} name
* @param {number} age
*/
function Person(name, age) {
/** @type {string} */
this.name = name;
/** @type {number} */
this.age = age;
}
/**
* @return {string}
*/
Person.prototype.greet = function() {
return 'Hello, I am ' + this.name;
};