home / skills / openclaw / skills / jsdoc-gen

jsdoc-gen skill

safe

This skill adds JSDoc or TSDoc comments to your exports automatically, enhancing readability and IDE hints without changing code.

npx playbooks add skill openclaw/skills --skill jsdoc-gen

Review the files below or copy the command above to add this skill to your agents.

Files (8)

SKILL.md

2.1 KB

---
name: jsdoc-gen
description: Add JSDoc or TSDoc comments to your code. Use when documentation is missing.
---

# JSDoc Generator

Your exported functions have no documentation. This tool adds JSDoc or TSDoc comments to all your exports without touching the actual code logic.

**One command. Zero config. Just works.**

## Quick Start

```bash
npx ai-docs src/ --style jsdoc
```

## What It Does

- Adds JSDoc/TSDoc comments to exported functions and classes
- Describes parameters, return values, and exceptions
- Preserves all existing code and comments
- Works on files, directories, or glob patterns

## Usage Examples

```bash
# Preview docs for a directory
npx ai-docs src/ --style jsdoc

# TSDoc style
npx ai-docs src/ --style tsdoc

# Write changes to files
npx ai-docs src/ --style jsdoc --write

# Single file
npx ai-docs src/utils.ts --style jsdoc

# Glob patterns
npx ai-docs "src/**/*.ts" --style tsdoc
```

## Best Practices

- **Preview first** - run without --write to see what changes
- **Focus on exports** - internal helpers don't need docs
- **Add examples** - especially for complex functions
- **Review output** - AI might miss nuances

## When to Use This

- Codebase has zero documentation
- Onboarding requires reading every function
- IDE hints are unhelpful without docs
- Preparing for open source release

## Part of the LXGIC Dev Toolkit

This is one of 110+ free developer tools built by LXGIC Studios. No paywalls, no sign-ups, no API keys on free tiers. Just tools that work.

**Find more:**
- GitHub: https://github.com/LXGIC-Studios
- Twitter: https://x.com/lxgicstudios
- Substack: https://lxgicstudios.substack.com
- Website: https://lxgic.dev

## Requirements

No install needed. Just run with npx. Node.js 18+ recommended. Needs OPENAI_API_KEY environment variable.

```bash
npx ai-docs --help
```

## How It Works

Reads your files, identifies exported functions, classes, and types, then generates appropriate documentation comments. The AI understands the function signatures and infers what each parameter does.

## License

MIT. Free forever. Use it however you want.

Overview

This skill adds JSDoc or TSDoc comments to your JavaScript and TypeScript exports so your public API is documented without changing code logic. It focuses on exported functions, classes, and types and can run on files, directories, or glob patterns with a simple command.

How this skill works

It scans the specified files, identifies exported functions, classes, and types, and generates descriptive JSDoc/TSDoc comments for parameters, return values, and thrown exceptions. The tool preserves existing code and comments and can either preview annotations or write them back to files based on your flags.

When to use it

Your codebase has little or no documentation for exports
Preparing a repository for open source release or code review
Onboarding new developers who need readable API docs
When your IDE provides poor or no hints for exported APIs
Before publishing packages to improve package consumers' experience

Best practices

Preview changes first by running without --write to review suggested comments
Focus on exported symbols; internal helpers often don’t need generated docs
Add or edit examples in generated comments for complex or ambiguous behavior
Run the tool as part of documentation workflows or pre-release checks
Review AI-generated descriptions and adjust domain-specific details manually

Example use cases

Generate JSDoc for an entire src/ directory: npx ai-docs src/ --style jsdoc
Create TSDoc annotations for TypeScript files with a glob: npx ai-docs "src/**/*.ts" --style tsdoc
Preview documentation changes before committing: npx ai-docs src/ --style jsdoc (no --write)
Apply changes directly to files to persist comments: npx ai-docs src/ --style jsdoc --write
Document a single utility file: npx ai-docs src/utils.ts --style jsdoc

FAQ

Does this change my code logic?

No. The tool only inserts or updates documentation comments and preserves all existing code and non-doc comments.

Do I need any API keys or runtime requirements?

It runs via npx and recommends Node.js 18+. An OPENAI_API_KEY environment variable may be required for AI generation depending on the release.