Accelint Ts Documentation

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` 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` 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 names and types 3. Standard patterns in the codebase

Rule of thumb: If a competent team member would ask "why?" or "what's the edge case?" - document it. If they'd say "obvious" - skip it.

3. Evaluating Documentation Sufficiency

Use this decision tree to determine if documentation is complete:

Step 1: Determine visibility tier

Is it exported (public API)?
  YES → Tier 1: Comprehensive documentation required
  NO  → Tier 2: Judgment-based minimal documentation

Step 2: Apply entity-specific requirements

Tier 1 (Exported) - Always Required:

• Description (purpose, usage context, "when to use" for appropriate entities)
• All @param with property documentation for objects
• @returns (unless void)
• @template with constraint explanations for generics
• @throws with triggering conditions
• At least one realistic @example

Tier 2 (Internal) - Judgment-Based:

• Brief description (one line acceptable)
• @param for non-obvious parameters only
• @returns if non-obvious
• @template for generics
• @example only if behavior is complex

Entity-Specific Additions:

• Classes (Tier 1): Constructor docs, public method docs, instantiation example
• Types/Interfaces (Tier 1): Property descriptions for all public properties
• Constants/Variables: Units/constraints if applicable (e.g., "milliseconds", "must be positive")

Sufficiency Checklist:

Before marking documentation as "sufficient", verify:

• [ ] All exported items have comprehensive documentation
• [ ] All @param tags describe what the parameter does (not just type info)
• [ ] All @returns tags describe what is returned in different scenarios
• [ ] All @example tags use proper code fences with language identifier
• [ ] No @returns on void functions
• [ ] Generic functions have @template for each type parameter
• [ ] Object parameters use dot notation for property documentation
• [ ] Descriptions focus on WHAT/WHY, not HOW

4. When References Are Insufficient

If you encounter scenarios not covered in references or standard patterns:

Fallback strategy: 1. Apply the two-tier rule (export vs internal) as your foundation 2. Prioritize clarity over completeness - better to document what you know than guess syntax 3. Use standard JSDoc conventions from TypeScript/JSDoc official documentation 4. Document your uncertainty with a NOTE marker: // NOTE: JSDoc syntax may need review for [specific case] 5. If truly ambiguous, ask the user for clarification rather than making assumptions

Common uncovered scenarios:

• Exotic TypeScript features (mapped types, conditional types, template literal types)
• Framework-specific patterns (React hooks with generics, Vue composables)
• Complex callback signatures with multiple overloads

For these, default to clear descriptions in natural language rather than incomplete JSDoc tags.

4. Use the Report Template (For Explicit Audit Requests)

When users explicitly request a documentation audit or invoke the skill directly (/accelint-ts-documentation <path>), use the standardized report format:

Template: `assets/output-report-template.md`

The audit report format provides:

• Numbered findings with clear before/after examples
• Categorization (Missing, Incomplete, Incorrect Syntax, Quality, Internal)
• References to detailed guidance (jsdoc.md, comments.md)
• Summary table for tracking all issues

When to use the audit template:

• Skill invoked directly via /accelint-ts-documentation <path>
• User explicitly requests "documentation audit" or "audit documentation"
• User asks to "review all documentation" across file(s)

When NOT to use the audit template:

• User asks to "add JSDoc to this function" (direct implementation)
• User asks "what's wrong with this comment?" (answer the question)
• User requests specific fixes (apply fixes directly without formal report)

Documentation Audit Anti-Patterns

When performing documentation audits, avoid these common mistakes:

❌ Incorrect: Over-documenting internal code

// Internal utility with verbose documentation
/**
 * Internal helper function that validates input
 * @internal
 * @param x - The input value
 * @returns True if valid, false otherwise
 * @example
 * ```typescript
 * if (isValid(data)) { ... }
 * ```
 */
function isValid(x: unknown): boolean {
  return x != null;
}

Why this is wrong: Internal docs rot faster than public API docs because they're adjacent to frequently-changed implementation. Team members can read the actual implementation faster than reading outdated documentation that creates confusion. Reserve comprehensive docs for stable exported APIs where consumers cannot access implementation.

✅ Correct: Minimal internal docs, comprehensive public API docs

// Internal utility - minimal documentation
/** Checks if value is not null/undefined */
function isValid(x: unknown): boolean {
  return x != null;
}

// Public API - comprehensive documentation even if "obvious"
/**
 * Validates user input data
 * @param data - User input to validate
 * @returns True if data is defined and not null
 * @example
 * ```typescript
 * if (validateInput(userData)) {
 *   processData(userData);
 * }
 * ```
 */
export function validateInput(data: unknown): boolean {
  return data != null;
}

❌ Incorrect: Documenting HOW instead of WHAT/WHY

// JSDoc describes implementation details
/**
 * Loops through array using reduce to accumulate values into a sum
 */
function sum(numbers: number[]): number {
  return numbers.reduce((a, b) => a + b, 0);
}

Why this is wrong: JSDoc appears in IDE autocomplete for API consumers who don't have access to implementation. Explaining HOW in JSDoc creates confusion ("why am I seeing implementation details in my autocomplete?") and increases refactoring surface area - every implementation change requires doc updates, leading to drift.

✅ Correct: Describe purpose and behavior, not implementation

/**
 * Calculates the sum of all numbers in the array
 * @param numbers - Array of numbers to sum
 * @returns The total sum, or 0 for empty array
 */
function sum(numbers: number[]): number {
  return numbers.reduce((a, b) => a + b, 0);
}

❌ Incorrect: Using vague comment markers

// Not actionable
// TODO: fix this
// TODO: improve performance

Why this is wrong: "TODO: fix this" creates diffusion of responsibility. After months pass, nobody knows if it's still relevant, who should fix it, or what "this" refers to. Vague markers accumulate as noise that reduces trust in ALL markers, making developers ignore even critical ones.

✅ Correct: Specific markers with ownership and context

// TODO(username): Replace with binary search for O(log n) lookup
// FIXME(username): Throws error on empty array, add guard clause

Documentation Quality Example

Excellent Public API Documentation

/**
 * Fetches user profile data from the authentication service
 *
 * Automatically retries up to 3 times on network failures with exponential
 * backoff. Throws if user is not authenticated or profile doesn't exist.
 *
 * @param userId - Unique identifier for the user profile to fetch
 * @param options - Configuration for fetch behavior
 * @param options.includeMetadata - Include account metadata (creation date, last login)
 * @param options.timeout - Request timeout in milliseconds (default: 5000)
 * @returns User profile with email, name, and optional metadata
 * @throws {AuthenticationError} When user session is expired or invalid
 * @throws {NotFoundError} When user profile doesn't exist
 * @throws {NetworkError} When all retry attempts are exhausted
 *
 * @example
 * ```typescript
 * // Basic usage
 * const profile = await fetchUserProfile('user-123');
 * console.log(profile.email);
 *
 * // With metadata and custom timeout
 * const profile = await fetchUserProfile('user-123', {
 *   includeMetadata: true,
 *   timeout: 10000
 * });
 * ```
 */
export async function fetchUserProfile(
  userId: string,
  options?: { includeMetadata?: boolean; timeout?: number }
): Promise<UserProfile> {
  // implementation
}

What makes this excellent:

• Describes hidden behaviors (retry logic with exponential backoff)
• Documents object parameters with dot notation (options.*)
• @throws lists all possible errors with triggering conditions
• @example shows both basic and advanced usage patterns
• Mentions defaults and constraints (timeout default: 5000)
• Focuses on WHAT/WHY (user needs), not HOW (implementation details)

Conflict Resolution Principles

When judgment calls conflict, apply these priorities:

1. Consistency > Perfection: Follow existing codebase patterns 2. Consumer > Maintainer: Public API docs serve users without your context - be comprehensive 3. Intent > Implementation: Document WHAT/WHY, not HOW 4. Stable > Churning: Comprehensive docs for stable code, minimal for high-churn code 5. Future clarity test: "Would this help me in 6 months?" If no, remove it

Edge Cases Require Reference Loading

Complex scenarios (deprecated APIs, overloaded functions, generic utility types, callback parameters, builder patterns, event emitters) require detailed syntax guidance. When encountering these:

Load jsdoc.md reference - Contains comprehensive examples for all edge cases with correct syntax patterns.

Key principle: Edge cases still follow the two-tier rule (export vs internal), but syntax details matter more. Don't guess - load the reference.

Code Documentation Audit

Abstract

Comprehensive guide for auditing and improving JavaScript/TypeScript documentation. Covers JSDoc standards, comment markers, and code comment quality. Each section includes one-line summaries here, with links to detailed examples in the references/ folder.

---

How to Use This Guide

1. Start here: Scan the rule summaries to identify documentation issues 2. Load references as needed: Click through to detailed examples only when implementing 3. Progressive loading: Each reference file is self-contained with ❌/✅ examples

This structure minimizes context usage while providing complete implementation guidance when needed.

---

Quick Reference

When to Document

Exported (Public API):

• ✅ Always comprehensive documentation (no exceptions)
• Required: description, @param, @returns, @template, @throws, @example

Internal Code:

• ✅ Document what's not obvious
• Required: description, @param (for non-obvious), @returns (unless void/obvious), @template
• Optional: @example, @throws

---

JSDoc Standards

Functions

All functions need: description, @param, @template (if generic), @returns (unless void). Exported functions also need @throws and @example. View detailed examples

Types and Interfaces

All types/interfaces need: description, @template (if generic). Exported types also need property descriptions. View detailed examples

Classes

All classes need: description, @template (if generic). Exported classes also need @example. View detailed examples

Constants

All constants need: description. Exported constants should include units/constraints if applicable. View detailed examples

Object Parameters

Use dot notation to document destructured parameters (e.g., props.children, config.timeout). View detailed examples

Code Fence Requirement

All @example tags MUST use code fences with language identifier (typescript, javascript, tsx, jsx). View detailed examples

---

Comment Quality

Comment Markers

Use TODO, FIXME, HACK, NOTE, REVIEW, PERF, DEBUG, REMARK with context and ownership. View detailed examples

Comments to Remove

Always remove: commented-out code, edit history, comments restating obvious code. View detailed examples

Comments to Preserve

Always keep: marker comments, linter directives, business logic explanations, docblocks. View detailed examples

Comment Placement

Move end-of-line comments to their own line above the code (improves readability). View detailed examples

---

Common Anti-Patterns

NEVER do these:

• ❌ @example without code fences (won't render properly)
• ❌ Over-document internal utilities (noise vs signal)
• ❌ Leave commented-out code (git preserves history)
• ❌ Document HOW instead of WHAT/WHY
• ❌ Use @returns for void functions
• ❌ Add TODO without context ("fix this" is useless)

See SKILL.md for detailed anti-pattern examples with corrections.

╭───────────────────────────╮ │ accelint-ts-documentation │ ╰───────────────────────────╯

<!-- Make sure to display this warning block to the user --> ┌─────────────────────────────────────────────────────┐ │ ⚠️ WARNING: This skill does it's best to process │ │ the context needed to suggest correct documentation │ │ but it can make mistakes in large systems. Please │ │ verify the correctness of the documentation. │ │ Particularly any suggested @links tags. │ └─────────────────────────────────────────────────────┘

Report: [Target Name]

<!-- INSTRUCTIONS FOR COMPLETING THIS TEMPLATE:

1. Replace [Target Name] with the file(s)/module being audited

2. FINDINGS STRUCTURE:

• Each finding should be numbered sequentially (1, 2, 3, etc.)
• Don't group issues - document each one individually
• Focus on showing the before/after clearly

3. EACH FINDING MUST INCLUDE:

• Clear title describing the issue
• Location (file:line)
• Current code with ❌ marker
• Clear explanation of the issue (bullet points)
• Category (see categories below)
• Reference (which references/*.md file)
• Recommended Fix with ✅ marker

4. CATEGORIES:

• Missing Documentation: Exported APIs with no JSDoc at all
• Incomplete Documentation: JSDoc missing @param, @returns, @example, @throws, etc.
• Incorrect Syntax: Wrong JSDoc syntax (@example without code fence, malformed tags)
• Quality Improvements: Comment markers, placement, removing obvious comments
• Internal Documentation: Non-obvious internal code needing explanation

5. REFERENCES:

• jsdoc.md - For JSDoc-related issues (missing, incomplete, incorrect syntax)
• comments.md - For inline comments, markers (TODO/FIXME), comment quality

6. SUMMARY TABLE:

• Keep it concise - one row per finding
• Should match the numbered findings above

See this file for a complete example of what a real audit looks like. -->

Findings

1. [Function/Type Name] - [Issue Type]

Location: [file:line]

// ❌ Current: [Brief description of problem]
[code snippet showing the issue]

Issue:

• [Point 1 explaining the documentation problem]
• [Point 2 with specifics about what's missing or incorrect]
• [Point 3 about impact on users/maintainers]

Category: [Missing Documentation|Incomplete Documentation|Incorrect Syntax|Quality Improvements|Internal Documentation] Reference: [jsdoc.md|comments.md]

Recommended Fix:

// ✅ [Brief description of solution]
[code snippet with proper documentation]

---

2. [Function/Type Name] - [Issue Type]

Location: [file:line]

// ❌ Current: [Brief description of problem]
[code snippet]

Issue:

• [Explanation of the problem]

Category: [Category Name] Reference: [filename.md]

Recommended Fix:

// ✅ [Brief description of solution]
[code snippet with fix]

---

3. [Continue for each finding...]

---

Summary

Total Issues: [N] By Category: [Category1] ([N]), [Category2] ([N]), [Category3] ([N])

Documentation Skill

Expert-level JavaScript/TypeScript documentation auditing skill with comprehensive guidance on JSDoc, comments, anti-patterns, and judgment frameworks.

Design Philosophy

This skill combines focused activation with expert judgment frameworks:

1. Enhanced activation - Triggers on specific keywords (@param, @returns, @template, @example, JSDoc, TODO, FIXME) 2. Expert anti-patterns - 6 critical "NEVER do this" patterns with examples 3. Thinking frameworks - Public/internal distinction with judgment criteria 4. Decision trees - Clear sufficiency evaluation for all code element types 5. Edge case coverage - Handles deprecated APIs, overloads, generics, callbacks, builders, events 6. Conflict resolution - Principles for resolving documentation dilemmas

What This Skill Covers

Core Capabilities

JSDoc Auditing

• Comprehensive standards for exported vs internal code
• Function, type, interface, class, and constant documentation
• Generic type parameter documentation (@template)
• Object parameter documentation with dot notation
• Example code fences with language identifiers
• Error documentation (@throws)

Comment Quality

• Comment markers (TODO, FIXME, HACK, NOTE, PERF, REVIEW, DEBUG, REMARK)
• Identifying comments to remove (dead code, edit history, obvious statements)
• Identifying comments to preserve (linter directives, business logic, markers)
• Comment placement best practices

Expert Guidance

• Anti-patterns with visual ❌/✅ examples
• Audit mindset and thinking frameworks
• Decision trees for documentation sufficiency
• Conflict resolution principles
• Edge case handling (deprecated APIs, overloads, callbacks, etc.)

Usage

Trigger Phrases

This skill activates when you use documentation-specific keywords:

Audit the documentation in src/utils/math.ts

Add JSDoc to all exported functions in src/api/client.ts

Add @param and @returns tags to this function

Review comments and add TODO/FIXME markers where appropriate

Document this function with @example

Fix comments in src/core/ - remove dead code and improve placement

Example Audit Output

The skill provides structured audit reports:

Missing Documentation:

• fetchUserProfile() (line 45) - missing @throws for AuthenticationError
• processData() (line 89) - missing @param for options.timeout
• UserConfig interface (line 12) - missing property descriptions

Syntax Issues:

• calculateTotal() (line 34) - @example without code fence
• authenticate() (line 67) - void function has @returns tag

Comment Quality:

• Line 23: Remove commented-out code
• Line 45: Move end-of-line comment above code
• Line 78: Add FIXME marker for known bug

How It Works

Activation & Loading (Drift-Resilient)

1. Verify Current Structure - Reads parent SKILL.md to confirm current file organization 2. Load Documentation References - Loads 5 expected files with fallback discovery if reorganized:

• jsdoc.md - JSDoc syntax and tag requirements
• comment-markers.md - TODO, FIXME, HACK markers
• comments-to-remove.md - What to delete
• comments-to-preserve.md - What to keep
• comments-placement.md - Where to put comments

3. Apply Audit Workflow - Uses thinking frameworks and decision trees

Hybrid approach provides specific file list for clarity while verifying against parent SKILL.md for drift-resilience.

Audit Process

Step 1: Determine Scope

• Is code exported (public API)? → Comprehensive docs required
• Is code internal? → Apply judgment frameworks

Step 2: Check Completeness

• Use decision trees for Functions, Types, Classes, Constants
• Verify all required tags present (@param, @returns, @template, @throws, @example)

Step 3: Validate Syntax

• @example tags must use code fences with language identifier
• Object parameters must use dot notation
• void functions should not have @returns
• Generic functions must include @template

Step 4: Review Comments

• Apply markers (TODO, FIXME, HACK, NOTE, etc.)
• Remove dead code and edit history
• Preserve linter directives and business logic
• Improve placement (move end-of-line comments above code)

Step 5: Report Findings

• Structured output with file:line references
• Categorized by issue type
• Specific, actionable recommendations

Key Features

🚫 Anti-Patterns (6 Critical Mistakes)

Visual ❌/✅ examples of common documentation mistakes:

• Approving @example without code fences
• Over-documenting internal code vs under-documenting public APIs
• Leaving commented-out code
• Documenting HOW instead of WHAT/WHY
• Using @returns for void functions
• Adding TODO without context

🧠 Thinking Frameworks

Two-Tier Approach:

• Public API → Always comprehensive (no exceptions)
• Internal code → Three judgment dimensions:
• Complexity vs Clarity
• Maintenance Burden
• Value vs Noise

🌲 Decision Trees

Clear sufficiency evaluation for:

• Functions/Methods (exported vs internal requirements)
• Types/Interfaces (with/without @example)
• Classes (constructor, methods, examples)
• Constants/Variables (when documentation is needed)

🔀 Conflict Resolution

Principles for resolving common dilemmas:

• Comprehensive vs Concise (favor comprehensive for public APIs)
• Document Complexity vs Avoid Noise (well-named internals need minimal docs)
• Stable API vs Changing Requirements (document current, note future with @remarks)
• Multiple Valid Approaches (consistency > perfection)

🎯 Edge Cases

Handling for special scenarios:

• Deprecated APIs (@deprecated, @see, migration paths)
• Overloaded functions (single doc block, multiple examples)
• Generic utility types (@template explanations, type transformations)
• Callback parameters (dot notation for parameters)
• Builder patterns (chain examples)
• Event emitters (event-specific payloads)

📚 Quality Examples

Side-by-side comparison of excellent vs poor documentation with annotated explanations showing why each approach succeeds or fails.

Benefits of Hybrid Design

Expert knowledge layer:

• Anti-patterns, thinking frameworks, and decision trees are unique to this skill
• Provides audit-specific expertise beyond general documentation rules
• ~640 lines of focused documentation guidance

Smart delegation:

• Implementation details (JSDoc syntax, comment rules) come from parent skill
• Avoids duplicating content that changes frequently
• Hybrid verification approach handles parent skill reorganization

Activation specificity:

• Enhanced description with specific JSDoc tags (@param, @returns, @template, @example)
• Triggers on documentation-specific phrases users actually say
• Higher activation accuracy than general-purpose parent skill

Comprehensive coverage:

• Standard cases (decision trees for all code element types)
• Edge cases (deprecated, overloads, generics, callbacks, builders, events)
• Conflicts (resolution principles for common dilemmas)
• Quality benchmarks (excellent vs poor examples)

Drift-resilient integration:

• Verifies parent structure before loading
• Fallback discovery if files reorganized
• Clear expected file list with pattern-based alternatives

Integration

Use this skill when:

• Documentation auditing is the primary focus
• You need expert judgment on what/how to document
• You're adding JSDoc to exported functions/types/classes
• You're reviewing comment quality and markers
• You need guidance on edge cases (deprecated, overloads, generics, etc.)

Skill Metrics

• Size: ~640 lines (SKILL.md)
• Knowledge ratio: 70% expert / 20% activation / 10% redundant
• Pattern: Navigation wrapper with substantial original content

License

Apache-2.0

Comment Quality Standards

Comment Markers

Use "better comment" markers for non-docblock comments to categorize different types of annotations:

• TODO: - Future changes or unimplemented features
• FIXME: - Known bugs or critical defects
• HACK: - Workarounds or sub-optimal solutions
• NOTE: - Important informational points
• REVIEW: - Areas requiring code review or scrutiny
• PERF: - Performance bottlenecks or optimizations
• DEBUG: - Temporary debugging code (remove later)
• REMARK: - General observations

❌ Incorrect: Vague markers without context

// TODO: fix this
// TODO: improve performance
// TODO: handle edge cases

✅ Correct: Specific markers with context and ownership

// TODO(username): Replace with binary search for O(log n) lookup
// FIXME(username): Throws error on empty array, add guard clause
// HACK(username): Temporary workaround for API bug #1234, remove when fixed

Comments to Remove

Always remove these types of comments during audits:

Commented-Out Code

Dead code should be deleted, not commented. Version control preserves history.

❌ Incorrect: Dead code should be removed

function process(data) {
  // const oldWay = transform(data);
  // return oldWay.map(x => x * 2);
  return newWay(data);
}

✅ Correct: Delete dead code

function process(data) {
  return newWay(data);
}

Edit History Comments

Comments like "added", "removed", "changed" should be removed. Git provides change history.

❌ Incorrect: Edit history in comments

// Added 2024-01-15: Support for new API
// Changed by John: Use async/await
// Removed error handling (not needed)
function fetchData() {
  // ...
}

✅ Correct: Remove edit history

function fetchData() {
  // ...
}

Comments Restating Code

Comments that merely restate what the code clearly does add no value.

❌ Incorrect: Obvious comment

// Increment counter by 1
counter++;

// Loop through all users
for (const user of users) {
  // ...
}

// Return true
return true;

✅ Correct: Only comment non-obvious intent

// Reset counter for next batch
counter = 0;

// Process users in registration order (stable sort required)
for (const user of users) {
  // ...
}

Comments to Preserve

Always keep these types of comments during audits:

Comments with Markers

All comments using TODO, FIXME, HACK, NOTE, REVIEW, PERF, DEBUG, or REMARK markers should be preserved.

✅ Correct: Preserve marker comments

// TODO(alice): Implement caching for repeated queries
// FIXME(bob): Race condition when concurrent requests
// PERF(charlie): This loop is O(n²), optimize to O(n log n)

Linter and Tool Directives

These have specific syntax required by tools and must not be modified.

✅ Correct: Preserve tool directives unchanged

// eslint-disable-next-line @typescript-eslint/no-explicit-any
const data: any = parseUnknownFormat(input);

// biome-ignore lint/suspicious/noExplicitAny: External API requires any
function processExternal(input: any): void {
  // ...
}

// prettier-ignore
const matrix = [
  1, 0, 0,
  0, 1, 0,
  0, 0, 1
];

// @ts-expect-error - Testing error handling
const result = functionThatThrows();

Business Logic Explanations

Comments explaining why code works a certain way (not what it does) are valuable.

✅ Correct: Preserve business logic explanations

// Apply 10% discount only on weekdays per marketing policy
const discount = isWeekday ? 0.10 : 0;

// Cache must be invalidated after 5 minutes due to API rate limits
const CACHE_TTL = 5 * 60 * 1000;

// Use binary search because data is pre-sorted by database
const index = binarySearch(sortedData, target);

Docblock Comments

All JSDoc comments should be preserved (and improved if incomplete).

✅ Correct: Preserve and enhance docblocks

/**
 * Calculates the total price including tax.
 * @param basePrice - Price before tax in dollars
 * @param taxRate - Tax rate as decimal (0.08 = 8%)
 * @returns Total price with tax applied
 */
function calculateTotal(basePrice: number, taxRate: number): number {
  return basePrice * (1 + taxRate);
}

Comments Placement

Move end-of-line comments to their own line above the code they describe. This improves readability and prevents comments from being lost at the end of long lines.

❌ Incorrect: End-of-line comments

const MAX_RETRIES = 3; // Maximum number of retry attempts
const TIMEOUT = 5000; // Request timeout in milliseconds

function process(data: Data): Result {
  const normalized = normalize(data); // Convert to standard format
  const validated = validate(normalized); // Check all required fields
  return transform(validated); // Apply business rules
}

✅ Correct: Comments above code

// Maximum number of retry attempts
const MAX_RETRIES = 3;

// Request timeout in milliseconds
const TIMEOUT = 5000;

function process(data: Data): Result {
  // Convert to standard format
  const normalized = normalize(data);

  // Check all required fields
  const validated = validate(normalized);

  // Apply business rules
  return transform(validated);
}

Exception: Short inline clarifications are acceptable

const result = value ?? fallback; // Use fallback if value is null/undefined
return items.filter(x => x > 0); // Remove negative values

JSDoc Documentation Standards

Scope

All functions, type aliases, interfaces, constants, and classes (both exported and internal) must have well-formed JSDoc comments.

Directive Comments Are Exempt

Tool directive comments must be left unchanged. These include:

• Linter directives: // eslint-disable-next-line, // biome-ignore lint/suspicious/noExplicitAny: reason
• Formatter directives: // prettier-ignore
• Tool-specific comments: // biome-ignore-all assist/source/organizeImports: reason
• Type checker directives: // @ts-expect-error, // @ts-ignore

These comments have specific syntaxes required by their respective tools and must not be modified or reformatted to follow JSDoc conventions. They serve a different purpose than documentation comments.

Exported code requires comprehensive documentation with all applicable tags.

Internal code may use reduced documentation: description, @template, @param, and @returns only (can omit @example and @throws).

@example Code Fence Requirement

All @example tags must use code fences with the appropriate language identifier:

• Use javascript for .js files
• Use typescript for .ts files
• Use jsx for .jsx files
• Use tsx for .tsx files

❌ Incorrect: No code fence

/**
 * @example
 * const result = add(1, 2); // 3
 */

❌ Incorrect: Code fence without language

/**
 * @example
 * ```
 * const result = add(1, 2); // 3
 * ```
 */

✅ Correct: Code fence with language identifier

/**
 * @example
 * ```typescript
 * const result = add(1, 2); // 3
 * ```
 */

Functions

Required (all functions)

• Description (clear summary)
• @param for each parameter
• @template for each generic type parameter
• @returns (unless return type is void)

Required (exported functions only)

• @throws for each thrown error type
• @example with working code snippet

Optional

• @remarks - Additional context
• @see / @link - Related references
• @deprecated - Deprecation notice

Examples

❌ Incorrect: Missing required tags

export function clamp(min: number, max: number, value: number): number {
  if (min > max) {
    throw new RangeError(`min (${min}) > max (${max})`);
  }
  return Math.max(min, Math.min(max, value));
}

✅ Correct: Complete documentation

/**
 * Clamps a number within the specified bounds.
 *
 * @param min - The lower bound to clamp to.
 * @param max - The upper bound to clamp to.
 * @param value - The number value to clamp to the given range.
 * @returns The clamped value.
 *
 * @throws {RangeError} Throws if min > max.
 *
 * @example
 * ```typescript
 * const value = clamp(5, 15, 10); // 10
 * const value = clamp(5, 15, 2);  // 5
 * const value = clamp(5, 15, 20); // 15
 * ```
 */
export function clamp(min: number, max: number, value: number): number {
  if (min > max) {
    throw new RangeError(`min (${min}) > max (${max})`);
  }
  return Math.max(min, Math.min(max, value));
}

❌ Incorrect: Generic function without @template

/**
 * Returns the first element of an array.
 *
 * @param arr - The array to get the first element from.
 * @returns The first element.
 */
function first<T>(arr: T[]): T | undefined {
  return arr[0];
}

✅ Correct: Generic function with @template

/**
 * Returns the first element of an array.
 *
 * @template T - The type of elements in the array.
 * @param arr - The array to get the first element from.
 * @returns The first element, or undefined if array is empty.
 *
 * @example
 * ```typescript
 * const num = first([1, 2, 3]); // 1
 * const str = first(['a', 'b']); // 'a'
 * const none = first([]); // undefined
 * ```
 */
function first<T>(arr: T[]): T | undefined {
  return arr[0];
}

❌ Incorrect: void function with @returns

/**
 * Logs a message to the console.
 *
 * @param message - The message to log.
 * @returns Nothing (incorrect - should be omitted for void).
 */
function log(message: string): void {
  console.log(message);
}

✅ Correct: void function without @returns

/**
 * Logs a message to the console.
 *
 * @param message - The message to log.
 *
 * @example
 * ```typescript
 * log('Hello, world!');
 * ```
 */
function log(message: string): void {
  console.log(message);
}

Object Parameters with Destructuring

When a function accepts an object parameter that is destructured, document the object properties using nested @param tags with dot notation. This provides developers with clear understanding of the expected object structure.

❌ Incorrect: Single @param without property details

/**
 * Container component for grouping multiple accordions together.
 *
 * @param props - Accordion components props.
 * @returns The rendered accordion group component.
 */
export function AccordionGroup({
  ref,
  children,
  className,
  variant = 'cozy',
  isDisabled,
  ...rest
}: AccordionGroupProps) {
  // ...
}

❌ Incorrect: Documenting each destructured parameter separately

/**
 * Container component for grouping multiple accordions together.
 *
 * @param ref - Ref object for the accordion group element.
 * @param children - Accordion components to include in the group.
 * @param className - Additional CSS class names.
 * @param variant - Visual density variant (compact or cozy).
 * @param isDisabled - Whether all accordions in the group are disabled.
 * @param rest - Additional DisclosureGroup props.
 * @returns The rendered accordion group component.
 */
export function AccordionGroup({
  ref,
  children,
  className,
  variant = 'cozy',
  isDisabled,
  ...rest
}: AccordionGroupProps) {
  // ...
}

✅ Correct: Documenting object parameter with nested properties

/**
 * Container component for grouping multiple accordions together with shared configuration.
 *
 * Provides coordinated behavior for multiple accordions, controlling
 * whether multiple sections can be expanded simultaneously.
 *
 * @param props - The accordion group props.
 * @param props.ref - Reference to the root div element.
 * @param props.children - Accordion components to render within the group.
 * @param props.className - Additional CSS class names.
 * @param props.variant - Visual variant of the accordions ('compact' or 'cozy').
 * @param props.isDisabled - Whether all accordions in the group are disabled.
 * @returns The accordion group component.
 *
 * @example
 * ```tsx
 * <AccordionGroup variant="compact">
 *   <Accordion title="Section 1">Content 1</Accordion>
 *   <Accordion title="Section 2">Content 2</Accordion>
 * </AccordionGroup>
 * ```
 */
export function AccordionGroup({
  ref,
  children,
  className,
  variant = 'cozy',
  isDisabled,
  ...rest
}: AccordionGroupProps) {
  // ...
}

✅ Correct: Nested object properties

/**
 * Initializes a database connection with configuration options.
 *
 * @param config - Database configuration options.
 * @param config.host - Database server hostname.
 * @param config.port - Database server port.
 * @param config.credentials - Authentication credentials.
 * @param config.credentials.username - Database username.
 * @param config.credentials.password - Database password.
 * @param config.pool - Connection pool settings.
 * @param config.pool.min - Minimum number of connections.
 * @param config.pool.max - Maximum number of connections.
 * @returns Database connection instance.
 *
 * @example
 * ```typescript
 * const db = initDatabase({
 *   host: 'localhost',
 *   port: 5432,
 *   credentials: { username: 'admin', password: 'secret' },
 *   pool: { min: 2, max: 10 }
 * });
 * ```
 */
function initDatabase(config: DatabaseConfig): Database {
  // ...
}

Types and Interfaces

Required (all types/interfaces)

• Description (clear summary)
• @template for each generic type parameter

Optional

• Property descriptions (inline)
• @remarks - Additional context

Examples

❌ Incorrect: Type without documentation

type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E };

✅ Correct: Type with complete documentation

/**
 * Represents the result of an operation that can succeed or fail.
 *
 * @template T - The type of the success value.
 * @template E - The type of the error.
 */
type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E };

❌ Incorrect: Interface without property descriptions

/**
 * Configuration for the API client.
 */
interface ApiConfig {
  baseUrl: string;
  timeout: number;
  retries: number;
}

✅ Correct: Interface with property descriptions

/**
 * Configuration for the API client.
 */
interface ApiConfig {
  /** The base URL for API requests. */
  baseUrl: string;

  /** Request timeout in milliseconds. */
  timeout: number;

  /** Number of times to retry failed requests. */
  retries: number;
}

Constants

Required (all constants)

• Description (clear summary)

Examples

❌ Incorrect: Constant without documentation

const MAX_RETRIES = 3;

✅ Correct: Constant with documentation

/**
 * Maximum number of retry attempts for failed requests.
 */
const MAX_RETRIES = 3;

✅ Correct: Complex constant with documentation

/**
 * HTTP status code mappings.
 */
const STATUS_CODES = {
  OK: 200,
  CREATED: 201,
  BAD_REQUEST: 400,
  NOT_FOUND: 404,
} as const;

Classes

Required (all classes)

• Description (clear summary)
• @template for each generic type parameter

Required (exported classes only)

• @example with working code snippet

Optional

• @remarks - Additional context
• @see / @link - Related references
• @deprecated - Deprecation notice

Examples

❌ Incorrect: Class without documentation

class Queue<T> {
  private items: T[] = [];

  enqueue(item: T): void {
    this.items.push(item);
  }

  dequeue(): T | undefined {
    return this.items.shift();
  }
}

✅ Correct: Class with complete documentation

/**
 * A generic FIFO (First-In-First-Out) queue.
 *
 * @template T - The type of elements in the queue.
 *
 * @example
 * ```typescript
 * const queue = new Queue<number>();
 * queue.enqueue(1);
 * queue.enqueue(2);
 * console.log(queue.dequeue()); // 1
 * console.log(queue.dequeue()); // 2
 * console.log(queue.dequeue()); // undefined
 * ```
 */
class Queue<T> {
  private items: T[] = [];

  /**
   * Adds an item to the end of the queue.
   *
   * @param item - The item to add to the queue.
   *
   * @example
   * ```typescript
   * queue.enqueue(42);
   * ```
   */
  enqueue(item: T): void {
    this.items.push(item);
  }

  /**
   * Removes and returns the item at the front of the queue.
   *
   * @returns The first item in the queue, or undefined if empty.
   *
   * @example
   * ```typescript
   * const item = queue.dequeue();
   * ```
   */
  dequeue(): T | undefined {
    return this.items.shift();
  }
}

❌ Incorrect: Deprecated class without notice

/**
 * Legacy user authentication handler.
 */
class AuthHandler {
  authenticate(token: string): boolean {
    // ...
  }
}

✅ Correct: Deprecated class with notice

/**
 * Legacy user authentication handler.
 *
 * @deprecated Use `AuthService` instead. This class will be removed in v3.0.
 * @see {@link AuthService}
 *
 * @example
 * ```typescript
 * // Don't use this:
 * const auth = new AuthHandler();
 *
 * // Use this instead:
 * const auth = new AuthService();
 * ```
 */
class AuthHandler {
  /**
   * Authenticates a user with a token.
   *
   * @param token - The authentication token.
   * @returns True if authentication succeeds.
   *
   * @deprecated Use `AuthService.authenticate()` instead.
   */
  authenticate(token: string): boolean {
    // ...
  }
}