JSDoc & TSDoc Documentation
Full Reference: See advanced.md for JSDoc type annotations in JavaScript, TypeDoc/API Extractor configuration, ESLint plugin setup, and README templates.
Deep Knowledge: Use mcp__documentation__fetch_docs with technology: jsdoc for comprehensive tag reference.
When NOT to Use This Skill
-
Plain JavaScript projects - Use the jsdoc skill for JavaScript-specific JSDoc patterns
-
Code comments (non-API) - TSDoc is for public API documentation, not inline code comments
-
Auto-generated docs from code - Use TypeDoc or API Extractor tools directly
TSDoc vs JSDoc
Feature JSDoc TSDoc
Purpose JS documentation + types TS documentation only
Type annotations @type , @param {Type}
Not needed (use TS types)
Standardization De facto Formal standard
Use TSDoc for TypeScript projects - types come from TypeScript, comments describe behavior.
Function Documentation
/**
- Calculates the total price including tax.
- @remarks
- This method uses the default tax rate unless overridden.
- For international orders, use {@link calculateInternationalPrice} instead.
- @param basePrice - The pre-tax price in cents
- @param taxRate - Tax rate as decimal (default: 0.1 for 10%)
- @returns The total price including tax in cents
- @throws {@link InvalidPriceError}
- Thrown if basePrice is negative
- @example
-
- const total = calculateTotalPrice(1000, 0.08);
- console.log(total); // 1080
-
- @beta */ function calculateTotalPrice(basePrice: number, taxRate = 0.1): number { if (basePrice < 0) { throw new InvalidPriceError('Price cannot be negative'); } return Math.round(basePrice * (1 + taxRate)); }
Interface Documentation
/**
- Configuration options for the HTTP client.
- @remarks
- All timeouts are in milliseconds.
- @public
/
interface HttpClientOptions {
/*
- Base URL for all requests.
- @example 'https://api.example.com/v1' */ baseUrl: string;
/**
- Request timeout in milliseconds.
- @defaultValue 30000 */ timeout?: number;
/**
- Maximum number of retry attempts for failed requests.
- @defaultValue 3 */ maxRetries?: number; }
All TSDoc Tags
Block Tags
Tag Usage
@param name - description
Parameter documentation
@returns description
Return value description
@throws {Type} description
Thrown exceptions
@example
Usage examples (code block)
@remarks
Extended description
@see
Related references
@deprecated reason
Mark as deprecated
@defaultValue value
Default value
@typeParam T - description
Generic type parameter
Modifier Tags
Tag Meaning
@public
Part of public API
@internal
Internal implementation
@alpha
Early preview, may change
@beta
Maturing, API may change
@readonly
Read-only property
@override
Overrides parent
Inline Tags
Tag Usage
{@link Target}
Link to symbol
{@link Target | text}
Link with custom text
{@inheritDoc Parent.method}
Inherit documentation
Anti-Patterns
Anti-Pattern Why It's Wrong Correct Approach
Documenting types in TypeScript Redundant, types already in signature Describe behavior, not types
Copy-pasting function signature Adds no value, desynchronizes Explain purpose, edge cases, examples
Missing @example for complex APIs Users don't know how to use it Always include usage examples
Using @deprecated without migration Users don't know what to use instead @deprecated Use {@link newFunction} instead
No @throws documentation Users don't know what to catch Document all thrown exceptions
Quick Troubleshooting
Issue Diagnosis Solution
VS Code not showing docs on hover Malformed JSDoc comment Ensure /** start and proper tag syntax
eslint-plugin-tsdoc errors Invalid TSDoc syntax Fix tag formatting per TSDoc spec
TypeDoc ignoring comments Wrong comment location Place JSDoc directly above declaration
{@link} not resolving Incorrect symbol reference Use fully qualified name or import path
Official References
Resource URL
TSDoc https://tsdoc.org/
JSDoc https://jsdoc.app/
TypeDoc https://typedoc.org/
API Extractor https://api-extractor.com/