add-docs

name	add-docs
description	Add comprehensive documentation to source code files across multiple languages. Automatically detects file language and applies appropriate documentation standards (Python docstrings, JSDoc, JavaDoc, Go doc comments, Rust doc comments, etc.). This skill should be used when documenting code, adding missing documentation to functions/classes/modules, or improving documentation standards across a codebase. Trigger phrases include "add documentation", "document this code", "add docstrings", "add JSDoc".
context	fork
agent	general-purpose
model	sonnet
argument-hint	<directory-path>
allowed-tools	["Glob","Read","Edit","TodoWrite","Bash(ruff:*)","Bash(black:*)","Bash(prettier:*)","Bash(eslint:*)","Bash(rustfmt:*)","Bash(gofmt:*)"]

Add Documentation

Overview

Add comprehensive documentation to source code files across multiple programming languages. The skill automatically detects the language of each file and applies the appropriate documentation standard, systematically processing each file while preserving all existing code logic.

Supported Languages

Language	Extensions	Documentation Style
Python	.py	Google-style docstrings
TypeScript/JavaScript	.ts, .js, .tsx, .jsx	JSDoc
Java	.java	JavaDoc
C#	.cs	XML documentation comments
Go	.go	Standard Go doc comments
Rust	.rs	/// doc comments
Ruby	.rb	RDoc/YARD
PHP	.php	PHPDoc
C/C++	.c, .cpp, .h, .hpp	Doxygen

Workflow

1. Parse Input and Discovery

Extract the directory path from the user's input. The path can be absolute or relative to the current working directory.

Use Glob to find all source code files in supported languages:

**/*.{py,ts,js,tsx,jsx,java,cs,go,rs,rb,php,c,cpp,h,hpp}

Group files by language for organized processing.

Create a TodoWrite list with one item per file, organized by language. Display to the user:

• Total number of files found
• Breakdown by language
• List of files to be processed

2. Process Each File

For each file in the todo list:

1. Mark the todo item as in_progress
2. Read the file completely
3. Detect the language based on file extension
4. Analyze the file to identify missing or incomplete documentation
5. Apply the appropriate documentation standard for that language

3. Documentation Standards by Language

Python (.py)

Google-style docstrings:

def process_data(data: DataFrame, config: Config) -> Result:
    """Process input data according to configuration settings.

    Applies transformation rules from the config to the input data,
    validates the results, and returns processed output.

    Args:
        data: Input data to be processed
        config: Configuration specifying transformation rules

    Returns:
        Processed data with transformations applied

    Raises:
        ValidationError: If data or config are invalid
        ProcessingError: If processing fails
    """

Add to:

• Module-level (top of file after imports)
• Classes
• Functions/methods
• Properties

TypeScript/JavaScript (.ts, .js, .tsx, .jsx)

JSDoc:

/**
 * Process input data according to configuration settings.
 *
 * Applies transformation rules from the config to the input data,
 * validates the results, and returns processed output.
 *
 * @param data - Input data to be processed
 * @param config - Configuration specifying transformation rules
 * @returns Processed data with transformations applied
 * @throws {ValidationError} If data or config are invalid
 * @throws {ProcessingError} If processing fails
 *
 * @example
 * const data = loadData('input.csv');
 * const config = new Config({ rules: [...] });
 * const result = processData(data, config);
 */
function processData(data: DataFrame, config: Config): Result {
    // implementation
}

Add to:

• Functions
• Classes
• Methods
• Interfaces (TypeScript)
• Type definitions (TypeScript)

Java (.java)

JavaDoc:

/**
 * Process input data according to configuration settings.
 *
 * <p>Applies transformation rules from the config to the input data,
 * validates the results, and returns processed output.</p>
 *
 * @param data Input data to be processed
 * @param config Configuration specifying transformation rules
 * @return Processed data with transformations applied
 * @throws ValidationException if data or config are invalid
 * @throws ProcessingException if processing fails
 */
public Result processData(DataFrame data, Config config) {
    // implementation
}

Add to:

• Classes
• Methods
• Fields (public/protected)
• Interfaces

Go (.go)

Standard Go doc comments:

// ProcessData processes input data according to configuration settings.
//
// Applies transformation rules from the config to the input data,
// validates the results, and returns processed output.
//
// Parameters:
//   - data: Input data to be processed
//   - config: Configuration specifying transformation rules
//
// Returns a Result containing processed data with transformations applied.
// Returns an error if data or config are invalid or processing fails.
func ProcessData(data *DataFrame, config *Config) (*Result, error) {
    // implementation
}

Add to:

• Package-level (top of file)
• Functions
• Types
• Methods

Rust (.rs)

Rust doc comments:

/// Process input data according to configuration settings.
///
/// Applies transformation rules from the config to the input data,
/// validates the results, and returns processed output.
///
/// # Arguments
///
/// * `data` - Input data to be processed
/// * `config` - Configuration specifying transformation rules
///
/// # Returns
///
/// Processed data with transformations applied
///
/// # Errors
///
/// Returns `ValidationError` if data or config are invalid.
/// Returns `ProcessingError` if processing fails.
///
/// # Examples
///
/// ```
/// let data = load_data("input.csv")?;
/// let config = Config::new(rules);
/// let result = process_data(&data, &config)?;
/// ```
pub fn process_data(data: &DataFrame, config: &Config) -> Result<ProcessedData> {
    // implementation
}

Add to:

• Modules
• Functions
• Structs
• Enums
• Traits
• Methods

C# (.cs)

XML documentation comments:

/// <summary>
/// Process input data according to configuration settings.
/// </summary>
/// <remarks>
/// Applies transformation rules from the config to the input data,
/// validates the results, and returns processed output.
/// </remarks>
/// <param name="data">Input data to be processed</param>
/// <param name="config">Configuration specifying transformation rules</param>
/// <returns>Processed data with transformations applied</returns>
/// <exception cref="ValidationException">Thrown if data or config are invalid</exception>
/// <exception cref="ProcessingException">Thrown if processing fails</exception>
public Result ProcessData(DataFrame data, Config config) {
    // implementation
}

Add to:

• Classes
• Methods
• Properties
• Events
• Interfaces

4. Editing Guidelines

When adding documentation to a file:

• Only modify documentation: Never change code logic, function signatures, or imports
• Preserve existing good documentation: If documentation is already complete and well-written, leave it unchanged
• Maintain code style: Respect existing indentation and formatting conventions
• Use Edit tool precisely: Make targeted edits to add documentation, not wholesale file rewrites
• Language-appropriate: Apply the documentation style that's standard for that language

5. Optional Formatting

After editing each file, optionally run language-appropriate formatters if available:

Python:

ruff format <file-path>
# or
black <file-path>

TypeScript/JavaScript:

prettier --write <file-path>
# or
eslint --fix <file-path>

Rust:

rustfmt <file-path>

Go:

gofmt -w <file-path>

Only run formatters if they complete successfully. If a formatter fails, skip it and continue.

6. Complete Processing

After processing each file:

1. Mark the todo item as completed
2. Continue to the next file
3. Process files one at a time - do not batch

7. Final Summary

After all files are processed, provide a summary:

• Total files processed (breakdown by language)
• Files that received new documentation
• Files that were already well-documented (skipped)
• Any files that had errors (if applicable)

Example summary:

Documentation Summary:
----------------------
Total files processed: 47

By language:
  Python:      23 files (15 updated, 8 already documented)
  TypeScript:  18 files (12 updated, 6 already documented)
  Rust:        6 files (4 updated, 2 already documented)

All files successfully documented!

Language Detection

Detect language by file extension:

Extension(s)	Language	Doc Style
.py	Python	Google-style docstrings
.ts, .tsx	TypeScript	JSDoc
.js, .jsx	JavaScript	JSDoc
.java	Java	JavaDoc
.cs	C#	XML comments
.go	Go	Go doc comments
.rs	Rust	/// doc comments
.rb	Ruby	RDoc/YARD
.php	PHP	PHPDoc
.c, .cpp, .h, .hpp	C/C++	Doxygen

Important Notes

• Work systematically through the todo list
• Process one file at a time and mark it complete before moving to the next
• If a file already has comprehensive documentation, mark it complete without changes
• Focus on clarity and usefulness, not verbosity
• Document the "why" and "what", not just repeating the code
• Respect existing codebase structure completely - this is a documentation-only operation
• When encountering mixed-language projects, process each language appropriately