JSDoc - Quick Reference

When NOT to Use This Skill

• TypeScript projects - Use the jsdoc-tsdoc skill for TSDoc and TypeScript-specific patterns
• JSDoc generation config - This is for writing JSDoc comments, not configuring the tool
• Complex type systems - TypeScript provides better type checking than JSDoc annotations
• API documentation hosting - Use documentation platforms (TypeDoc, Docusaurus, etc.)

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: jsdoc for comprehensive tag reference, type expressions, and generation options.

Pattern Essenziali

Function Documentation

/**
 * Calculates the sum of two numbers.
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {number} The sum of a and b
 * @example
 * const result = add(2, 3); // 5
 */
function add(a, b) {
  return a + b;
}

Object Types

/**
 * @typedef {Object} User
 * @property {string} id - Unique identifier
 * @property {string} name - Full name
 * @property {string} email - Email address
 * @property {boolean} [active=true] - Optional, defaults to true
 */

/**
 * Creates a new user.
 * @param {User} userData - The user data
 * @returns {Promise<User>} The created user
 */
async function createUser(userData) {
  // ...
}

Class Documentation

/**
 * Represents a user in the system.
 * @class
 */
class User {
  /**
   * Creates a User instance.
   * @param {string} name - User's name
   * @param {string} email - User's email
   */
  constructor(name, email) {
    /** @type {string} */
    this.name = name;
    /** @type {string} */
    this.email = email;
  }

  /**
   * Gets the user's display name.
   * @returns {string} Display name
   */
  getDisplayName() {
    return this.name;
  }
}

Callback Types

/**
 * @callback FetchCallback
 * @param {Error|null} error - Error if failed
 * @param {Object} data - Response data
 */

/**
 * Fetches data from the API.
 * @param {string} url - The URL to fetch
 * @param {FetchCallback} callback - Called with the result
 */
function fetchData(url, callback) {
  // ...
}

Generic Types

/**
 * @template T
 * @param {T[]} array - Array of items
 * @returns {T|undefined} First item or undefined
 */
function first(array) {
  return array[0];
}

Module Documentation

/**
 * @module utils/string
 * @description String utility functions
 */

/**
 * Capitalizes the first letter.
 * @param {string} str - Input string
 * @returns {string} Capitalized string
 */
export function capitalize(str) {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

Anti-Patterns

Anti-Pattern	Why It's Wrong	Correct Approach
No documentation at all	No IDE hints, hard to use API	Document at least public functions and complex logic
Copying implementation as comment	Adds no value, becomes outdated	Describe behavior, not implementation
Missing @param types	No type checking or autocomplete	Always specify parameter types
Outdated documentation	Misleading, worse than none	Update docs when changing code
Over-documenting obvious code	Clutters code, maintenance burden	Document complex logic, skip trivial getters/setters
Using wrong tag for purpose	Confuses tools, incorrect types	Use @typedef for types, @callback for functions
Not importing types	Broken type references	Use @typedef {import('./types').Type}
Duplicate type info in TypeScript	Redundant, desynchronizes	Let TypeScript types speak for themselves

Quick Troubleshooting

Issue	Diagnosis	Solution
IDE not showing type hints	JSDoc comments malformed or incomplete	Ensure @param {Type} and @returns {Type} are present
Type errors in VS Code	Incorrect JSDoc type syntax	Use TypeScript-style types: {string|null} not {?string}
Broken type imports	Wrong import path in @typedef	Use @typedef {import('./file').TypeName} with correct path
Generic types not working	Improper @template usage	Declare @template T before using it in params
Documentation not generated	JSDoc tool not configured	Run jsdoc -c jsdoc.json with proper config
Optional params showing as required	Missing [] in param name	Use @param {string} [optional] or {string=}
Types not recognized	Typo or undeclared typedef	Define types with @typedef before use
Return type ignored	Missing @returns tag	Always document return value with @returns {Type}

Related Skills

• TSDoc/JSDoc
• TypeScript