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
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
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:
Consistency > Perfection
Follow existing codebase patterns
Consumer > Maintainer
Public API docs serve users without your context - be comprehensive
Intent > Implementation
Document WHAT/WHY, not HOW
Stable > Churning
Comprehensive docs for stable code, minimal for high-churn code
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.