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