doc-generator
Generate documentation for code including JSDoc, docstrings, README, and API docs. Use when documenting code, creating README files, or generating API documentation.
When & Why to Use This Skill
The Doc Generator skill is a comprehensive tool designed to automate the creation and maintenance of technical documentation. It streamlines the development workflow by generating high-quality JSDoc/TSDoc comments, professional README files, detailed API references, and structured CHANGELOGs directly from source code. By leveraging filesystem tools, it analyzes code structures to ensure documentation is accurate, consistent, and follows industry best practices, significantly reducing the manual overhead for developers and technical writers.
Use Cases
- Automated JSDoc/TSDoc Generation: Quickly add descriptive comments, parameter definitions, and return types to undocumented functions and classes in JavaScript or TypeScript projects.
- Project Onboarding: Generate standardized README.md files including installation steps, usage examples, and contribution guidelines to help new developers get started faster.
- API Documentation Maintenance: Automatically extract interface definitions and function signatures to create up-to-date API references for internal or external stakeholders.
- Release Management: Maintain a structured CHANGELOG by summarizing recent code changes, bug fixes, and new features in a clear, versioned format.
- Documentation Auditing: Use the built-in workflow to scan codebases for missing documentation and ensure all public APIs meet project-specific documentation standards.
| name | doc-generator |
|---|---|
| description | Generate documentation for code including JSDoc, docstrings, README, and API docs. Use when documenting code, creating README files, or generating API documentation. |
| allowed-tools | Bash, Read, Write, Grep, Glob |
Doc Generator
Version: 1.0.0 Purpose: Generate comprehensive documentation
Triggers
| Trigger | Examples |
|---|---|
| Document | "document this", "ドキュメント生成", "add docs" |
| README | "create README", "README作成" |
| API docs | "generate API docs", "API文書" |
| JSDoc | "add JSDoc", "コメント追加" |
Documentation Types
1. JSDoc/TSDoc
/**
* Calculates the total price including tax.
*
* @param items - Array of items with price property
* @param taxRate - Tax rate as decimal (e.g., 0.1 for 10%)
* @returns Total price including tax
*
* @example
* ```ts
* const total = calculateTotal([{ price: 100 }], 0.1);
* // Returns: 110
* ```
*
* @throws {Error} If items array is empty
* @see {@link Item} for item structure
*/
function calculateTotal(items: Item[], taxRate: number): number {
// implementation
}
2. Interface Documentation
/**
* Represents a user in the system.
*
* @interface User
* @property {string} id - Unique identifier
* @property {string} email - User's email address
* @property {Date} createdAt - Account creation timestamp
*/
interface User {
id: string;
email: string;
createdAt: Date;
}
3. README Structure
# Project Name
> One-line description
[](https://npmjs.com/package/package-name)
[](LICENSE)
## Features
- Feature 1
- Feature 2
## Installation
\`\`\`bash
npm install package-name
\`\`\`
## Quick Start
\`\`\`typescript
import { something } from 'package-name';
const result = something();
\`\`\`
## API Reference
### `functionName(param)`
Description of function.
**Parameters:**
- `param` (Type) - Description
**Returns:** Type - Description
**Example:**
\`\`\`typescript
const result = functionName('value');
\`\`\`
## Configuration
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| option1 | string | 'default' | Description |
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
MIT
4. CHANGELOG
# Changelog
All notable changes to this project will be documented in this file.
## [1.2.0] - 2025-01-15
### Added
- New feature X (#123)
### Changed
- Updated dependency Y
### Fixed
- Bug in Z (#124)
### Deprecated
- Old API method
### Removed
- Legacy code
### Security
- Fixed vulnerability
Workflow
Step 1: Analyze Code
# Find undocumented functions
grep -r "^export function" src/ | grep -v "/\*\*"
Step 2: Generate Docs
For each function/class:
- Read implementation
- Understand purpose
- Write description
- Add parameters
- Add return type
- Add examples
Step 3: Verify
# TypeScript doc check
npx typedoc --validation
# Lint docs
npx eslint --rule 'jsdoc/*' src/
Best Practices
Do
/**
* Validates email format.
*
* @param email - Email address to validate
* @returns True if email is valid
*/
function isValidEmail(email: string): boolean { }
Don't
/**
* This function validates emails.
* It takes an email parameter.
* It returns a boolean.
*/
function isValidEmail(email: string): boolean { }
Templates
Function Doc
/**
* [Brief description in imperative mood]
*
* [Longer description if needed]
*
* @param paramName - [Description]
* @returns [Description]
*
* @example
* \`\`\`ts
* [Usage example]
* \`\`\`
*
* @throws {ErrorType} [When this error occurs]
* @since [version]
* @deprecated [Use X instead]
*/
Class Doc
/**
* [Brief description]
*
* [Longer description]
*
* @example
* \`\`\`ts
* const instance = new ClassName(options);
* instance.method();
* \`\`\`
*/
class ClassName { }
Checklist
- All public APIs documented
- Examples included
- Parameters described
- Return values described
- Errors documented
- README is current
- CHANGELOG updated