---

name: jsdoc-tsdoc description: | JSDoc and TSDoc documentation standards. Covers syntax, tags, TypeScript integration, documentation generation, and API documentation best practices.

USE WHEN: user mentions "TSDoc", "TypeScript documentation", "API documentation", asks about "documenting TypeScript", "@param", "@returns", "TypeDoc", "API Extractor", "documentation tags"

DO NOT USE FOR: JavaScript-only JSDoc - use jsdoc skill for plain JavaScript allowed-tools: Read, Grep, Glob, Write, Edit

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
 * ```typescript
 * 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/