SuperAPI AI Directory

doc-generator

General & other

View repository

Updated 10-16 08:45

About this skill

Doc Generator

Version: 1.0.0 Purpose: Generate comprehensive documentation


Triggers

Trigger Examples
Document "document this", "document generation", "add docs"
README "create README", "create README"
API docs "generate API docs", "API documentation"
JSDoc "add JSDoc", "add comments"

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

[![npm](https://img.shields.io/npm/v/package-name)](https://npmjs.com/package/package-name)
[![License](https://img.shields.io/npm/l/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:

  1. Read implementation
  2. Understand purpose
  3. Write description
  4. Add parameters
  5. Add return type
  6. 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