document-code

---
name: document-code
description: Apply Google Style documentation standards to Python, Go, TypeScript, and Terraform code. Use when writing or reviewing code that needs docstrings/comments/JSDoc, when asked to "document this code", "add docstrings", "follow Google Style", or when improving code documentation quality. Supports Python docstrings, Go comments, TypeScript JSDoc, and Terraform variable/output descriptions. Enforces consistent, professional documentation standards.
---

# Code Documentation Standards

Apply Google Style documentation standards to Python (docstrings), Go (comments), TypeScript (JSDoc), and Terraform (descriptions). Ensures consistent, professional, and comprehensive code documentation across multiple languages.

## When to Apply This Skill

Use this skill when:

- Writing new functions, classes, or packages
- Reviewing code for documentation quality
- User requests "document this code" or "add docstrings"
- User mentions "Google Style" or documentation standards
- Refactoring code that lacks proper documentation
- Creating code examples that should be well-documented

## Core Principles

1. **Clarity**: Documentation should be immediately understandable
2. **Completeness**: Document all public APIs, parameters, returns, exceptions
3. **Consistency**: Follow language-specific Google Style conventions
4. **Conciseness**: Be thorough but avoid redundancy
5. **Examples**: Include usage examples for complex functionality

## Workflow

### 1. Detect Language

Identify the programming language:

- **Python**: Look for `.py` files, `def`, `class` keywords, type hints
- **Go**: Look for `.go` files, `func`, `type`, `package` keywords
- **TypeScript**: Look for `.ts` / `.tsx` files, `interface`, `type`, `export`, `import` keywords
- **Terraform**: Look for `.tf` files, `resource`, `variable`, `module` keywords

### 2. Apply Appropriate Standard

Read the corresponding reference file:

- **Python**: Read `references/python_google_style.md` for complete docstring standards
- **Go**: Read `references/go_google_style.md` for complete comment standards
- **TypeScript**: Read `references/typescript_google_style.md` for complete JSDoc standards
- **Terraform**: Read `references/terraform_style.md` for complete description standards

### 3. Document Code Elements

Apply documentation to all appropriate code elements:

**Python**:

- Module-level docstrings
- Class docstrings
- Method/function docstrings
- Important variables/constants

**Go**:

- Package comments
- Type comments
- Function comments
- Important constants/variables

**TypeScript**:

- `@fileoverview` JSDoc (file-level)
- Interface and type alias JSDoc
- Class and constructor JSDoc
- Method and function JSDoc
- Exported constants and enums

**Terraform**:

- Variable descriptions
- Output descriptions
- Resource comments
- Module descriptions

### 4. Quality Checks

Before finalizing, verify:

- All public APIs are documented
- Parameters and returns are described
- Exceptions/errors are documented
- Examples are provided for complex functions
- Formatting follows Google Style exactly
- No redundant or obvious documentation

### 5. Provide Feedback

When reviewing code:

- Point out missing documentation
- Suggest improvements to existing docs
- Provide corrected examples
- Explain why certain documentation is important

## Documentation Coverage

### Python - What to Document

**Always Document**:

- Public modules (module-level docstring)
- Public classes (class docstring)
- Public methods and functions (method docstring)
- `__init__` methods (explain parameters)

**Consider Documenting**:

- Complex private functions (with leading underscore)
- Non-obvious class attributes
- Module-level constants

**Don't Document**:

- Self-explanatory code (e.g., simple getters/setters)
- Override methods that just call super() without changes
- Trivial one-liner functions with obvious behavior

### Go - What to Document

**Always Document**:

- Package (package comment before package declaration)
- Exported types (structs, interfaces)
- Exported functions and methods
- Exported constants and variables

**Consider Documenting**:

- Complex unexported functions
- Non-obvious implementation details
- Important internal structures

**Don't Document**:

- Trivial getters/setters
- Self-explanatory code
- Override methods without new behavior

### TypeScript - What to Document

**Always Document**:

- All exported functions, classes, interfaces, type aliases, and enums
- Constructor parameters when using parameter properties (via `@param`)
- Class properties that are not self-evident from their names
- Thrown errors (`@throws`)
- Non-trivial return values (`@returns`)

**Consider Documenting**:

- Complex private methods (use `//` inline comments, not JSDoc)
- Non-obvious type constraints or invariants
- Performance characteristics of algorithms
- Side effects of functions

**Don't Document**:

- Trivial getters/setters where the name is fully self-explanatory
- Override methods that purely delegate to `super` without changes
- Implementation details already obvious from types and code

### Terraform - What to Document

**Always Document**:

- All variables (description field)
- All outputs (description field)
- Module purpose (README.md)
- Complex resources (inline comments)

**Consider Documenting**:

- Data sources with complex filters
- Non-obvious resource dependencies
- Conditional resource creation logic

**Don't Document**:

- Self-explanatory variable names
- Simple pass-through outputs
- Standard resource configurations

## Special Cases

### Python Type Hints

When using type hints, docstrings can be more concise:

```python
def add(a: int, b: int) -> int:
    """Add two integers.

    Args:
        a: First integer.
        b: Second integer.

    Returns:
        The sum of a and b.
    """
    return a + b
```

Type information is already in the signature, so Args and Returns can be brief.

### Go Error Returns

Always document what errors a function can return:

```go
// ReadConfig reads and parses the configuration file.
//
// Returns an error if the file cannot be read or contains invalid YAML.
func ReadConfig(path string) (*Config, error) {
    // implementation
}
```

### TypeScript JSDoc and Type Hints

With TypeScript, types are enforced by the compiler so JSDoc should focus on
_semantics_, not re-stating types. Use `@param`, `@returns`, and `@throws`:

````ts
/**
 * Fetches user profile data from the remote API.
 *
 * @param userId - Unique identifier for the user (UUID or numeric ID).
 * @returns Promise resolving to the user's profile.
 * @throws {HttpError} On non-2xx HTTP responses.
 * @throws {TimeoutError} If the request exceeds the configured timeout.
 *
 * @example
 * ```ts
 * const profile = await fetchUserProfile('user-123');
 * console.log(profile.displayName);
 * ```
 */
export async function fetchUserProfile(userId: string): Promise<UserProfile> {
  // implementation
}
````

Named exports only – never `export default`. File-level `@fileoverview` when
the module's purpose is not obvious from its name.

#### TypeScript-specific rules (Google Style)

**File structure** — sections separated by exactly one blank line, in this order:

1. Copyright/license JSDoc (if required)
2. `@fileoverview` JSDoc (if needed)
3. Imports
4. Implementation

**JSDoc placement** — always _before_ decorators, with no blank line between
the JSDoc and the decorator:

```ts
/** Root application module. */
@NgModule({declarations: [AppComponent]})
export class AppModule {}
```

**What to skip** — do not re-state types in `@param`/`@returns`; the compiler
enforces them. Document _semantics_, constraints, and edge cases instead.

**Interfaces vs type aliases** — use `interface` for object shapes; use `type`
for unions, intersections, and mapped types.

**Naming quick-reference**:

| Category | Convention | Example |
|---|---|---|
| Class / Interface / Enum | `UpperCamelCase` | `UserService` |
| Function / method / variable | `lowerCamelCase` | `fetchUser()` |
| Module-level constant | `CONSTANT_CASE` | `MAX_RETRIES` |
| Observable (convention) | `lowerCamelCase$` | `user$` |

> For the complete reference — generator functions, getters/setters, decorators,
> import styles, enum documentation — read `references/typescript_google_style.md`.

### Complex Algorithms

For complex logic, add inline comments AND comprehensive function documentation:

```python
def dijkstra(graph: Graph, start: Node) -> dict[Node, float]:
    """Find shortest paths using Dijkstra's algorithm.

    Implements Dijkstra's single-source shortest path algorithm
    using a priority queue for O((V + E) log V) complexity.

    Args:
        graph: Weighted graph with non-negative edge weights.
        start: Starting node for path calculations.

    Returns:
        Dictionary mapping each node to its shortest distance from start.
        Unreachable nodes are not included in the result.

    Raises:
        ValueError: If graph contains negative edge weights.

    Example:
        >>> graph = Graph()
        >>> graph.add_edge("A", "B", 4)
        >>> graph.add_edge("A", "C", 2)
        >>> distances = dijkstra(graph, "A")
        >>> distances["B"]
        4
    """
    # Implementation with inline comments for complex parts
```

## Output Format

When adding documentation to code:

1. **Present the documented code** with proper formatting
2. **Explain what was added** if the changes are significant
3. **Highlight any decisions** made about what to document or not document

## Avoid

- Generic or placeholder documentation ("This function does stuff")
- Redundant documentation that just repeats the code ("This adds a and b")
- Over-documentation of obvious code
- Inconsistent formatting within the same file
- Missing critical information (parameters, exceptions, edge cases)
- Documentation that becomes outdated as code changes

## Resources

### references/python_google_style.md

Complete Python docstring standard with:

- Module, class, and function docstring formats
- Args, Returns, Raises, Yields sections
- Type hint integration
- Examples for common patterns
- Edge cases and best practices

### references/go_google_style.md

Complete Go comment standard with:

- Package comment format
- Function and method comment format
- Type comment format
- Documentation for errors
- Examples for common patterns
- godoc integration notes

### references/typescript_google_style.md

Complete TypeScript JSDoc standard with:

- File structure and `@fileoverview` format
- Class, interface, and type alias JSDoc
- Function, method, and async function JSDoc
- Generator function documentation
- Enum documentation and naming conventions
- Import/export rules (named exports only, no `export default`)
- Naming conventions table (UpperCamelCase, lowerCamelCase, CONSTANT_CASE)
- What to document vs. what to skip
- Decorator placement rules
- Complete annotated example

### references/terraform_style.md

Complete Terraform documentation standard with:

- Variable description format
- Output description format
- Module documentation structure
- Inline comments for complex resources
- Examples for common patterns
- terraform-docs integration

## Quality Standards

All code documentation must:

- Start with a concise one-line summary
- Use proper grammar and punctuation
- Follow language-specific formatting (indentation, delimiters)
- Include examples for non-trivial public APIs
- Document all parameters, returns, and errors/exceptions
- Be maintained when code changes

• SKILL.md 11 KB
• references/go_google_style.md 15 KB
• references/python_google_style.md 15 KB
• references/terraform_style.md 17 KB
• references/typescript_google_style.md 17 KB