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'.
Comprehensive skill for improving JavaScript/TypeScript documentation, including JSDoc comments, comment markers, and general comment quality.
Use this skill when the task involves:
Do not activate for:
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.
Apply this thinking framework before auditing:
Question 1: Who is the reader?
Question 2: Opacity vs Complexity?
Question 3: Maintenance cost trade-off?
After applying the thinking framework:
Is this exported (public API)? → YES: Comprehensive documentation REQUIRED
Is this internal code? → Apply judgment: Document what's NOT self-evident from:
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.
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:
Tier 2 (Internal) - Judgment-Based:
Entity-Specific Additions:
Sufficiency Checklist:
Before marking documentation as "sufficient", verify:
If you encounter scenarios not covered in references or standard patterns:
Fallback strategy:
// NOTE: JSDoc syntax may need review for [specific case]Common uncovered scenarios:
For these, default to clear descriptions in natural language rather than incomplete JSDoc tags.
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:
When to use the audit template:
/accelint-ts-documentation <path>When NOT to use the audit template:
When performing documentation audits, avoid these common mistakes:
// 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.
// 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;
}
// 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.
/**
* 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);
}
// 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.
// TODO(username): Replace with binary search for O(log n) lookup
// FIXME(username): Throws error on empty array, add guard clause
/**
* 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:
When judgment calls conflict, apply these priorities:
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.