accelint-ts-documentation

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: accelint-ts-documentation
description: Audit and improve JavaScript/TypeScript documentation including JSDoc comments (@param, @returns, @template, @example), comment markers (TODO, FIXME, HACK), and code comment quality. Use when asked to 'add JSDoc', 'document this function', 'audit documentation', 'fix comments', 'add TODO/FIXME markers', or 'improve code documentation'.
license: Apache-2.0
metadata:
  author: accelint
  version: "1.1.0"
---

# Code Documentation Skill

Comprehensive skill for improving JavaScript/TypeScript documentation, including JSDoc comments, comment markers, and general comment quality.

## When to Activate This Skill

Use this skill when the task involves:

### JSDoc Documentation
- Adding JSDoc comments to exported functions, types, interfaces, or classes
- Validating JSDoc completeness (missing @param, @returns, @template tags)
- Ensuring JSDoc @example tags use proper code fences
- Documenting object parameters with destructuring using dot notation

### Comment Quality
- Identifying and categorizing comments using proper markers (TODO, FIXME, HACK, NOTE, PERF, REVIEW, DEBUG, REMARK)
- Removing unnecessary comments (commented-out code, edit history, obvious statements)
- Preserving important comments (markers, linter directives, business logic)
- Improving comment placement (moving end-of-line comments above code)

### Documentation Audits
- Reviewing code for documentation completeness
- Ensuring exported code has comprehensive documentation
- Validating internal code has minimum required documentation

## When NOT to Use This Skill

Do not activate for:
- General code quality issues (use accelint-ts-best-practices instead)
- Performance optimization (use accelint-ts-performance instead)
- Type safety improvements (use accelint-ts-best-practices instead)
- Framework-specific documentation (React PropTypes, Vue props, etc.)

## How to Use

### 1. Load References Based on Task Type

**For JSDoc additions/validation:**

**MANDATORY**: Read [`jsdoc.md`](references/jsdoc.md) in full before implementing.
Critical content: @example code fence syntax (failures common here), object parameter dot notation, @template requirements, edge cases.

**Do NOT load** `comments.md` unless the task explicitly mentions comment markers (TODO, FIXME, etc.) or comment quality issues.

**For comment quality audits:**

**MANDATORY**: Read [`comments.md`](references/comments.md) in full before implementing.
Critical content: Comment marker standards, what to remove vs preserve, placement rules.

**Do NOT load** `jsdoc.md` unless the task explicitly mentions JSDoc tags (@param, @returns, etc.) or function/type documentation.

**Do NOT load any references** when only answering questions (not implementing changes) or task is general code quality.

### 2. Expert Judgment Framework

Apply this thinking framework before auditing:

**Question 1: Who is the reader?**
- API consumers: Lack implementation context → Document comprehensively
- Team members: Have codebase context → Document non-self-evident behaviors only
- Future you (6 months): Will forget subtle decisions → Document rationale

**Question 2: Opacity vs Complexity?**
- Opacity = Intent is hidden → Must document (e.g., cache.invalidate() - why? performance? correctness?)
- Complexity = Implementation is intricate → Implementation comments, not JSDoc

**Question 3: Maintenance cost trade-off?**
- High churn code: Minimal docs (won't stay accurate)
- Stable API: Comprehensive docs (will stay accurate)
- Internal utilities: Brief docs (low reader count × low frequency = minimal ROI)

#### Two-Tier Decision Rule

After applying the thinking framework:

**Is this exported (public API)?**
→ YES: Comprehensive documentation REQUIRED
- All @param, @returns, @template, @throws, @example
- Even if "obvious" - consumers lack your context

**Is this internal code?**
→ Apply judgment: Document what's NOT self-evident from:
1. Function name and type signature
2. Parameter n