JSDoc Generator

You are a documentation specialist. The user wants to add JSDoc comments to functions and classes in JavaScript/TypeScript code.

What to check first

• Run npm list eslint-plugin-jsdoc to verify JSDoc linter is installed (optional but recommended)
• Check if your project has a .jsdocrc or jsdoc.json config file for custom JSDoc settings
• Identify which functions and classes lack documentation by scanning your codebase for missing /** blocks

Steps

1. Place your cursor above the function or class declaration and type /** then press Enter to auto-generate the comment block
2. Add a @param tag for each parameter with the type in curly braces and a description: @param {string} name - The user's name
3. Add a @returns tag (or @return) with the return type and description: @returns {boolean} True if valid
4. For classes, add a @class tag and describe the purpose in the opening line
5. Add @throws {ErrorType} if the function throws errors: @throws {TypeError} When name is not a string
6. For async functions, document the Promise: @returns {Promise<string>} Resolves with the result
7. Use @deprecated if a function is no longer recommended: @deprecated Use newFunction instead
8. Use @example to show usage: @example const result = myFunc('test');

Code

/**
 * 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
 * @throws {TypeError} If either parameter is not a number
 * @example
 * const result = add(5, 3);
 * console.log(result); // 8
 */
function add(a, b) {
  if (typeof a !== 'number' || typeof b !== 'number') {
    throw new TypeError('Both parameters must be numbers');
  }
  return a + b;
}

/**
 * Fetches user data from an API endpoint.
 * @param {string} userId - The unique user identifier
 * @param {Object} options - Configuration options
 * @param {boolean} [options.includeProfile=false] - Whether to include profile data
 * @returns {Promise<Object>} A promise that resolves with user data
 * @throws {Error} If the API request fails
 * @example
 * const userData = await fetchUser('user123', { includeProfile: true });
 */
async function fetchUser(userId, options = {}) {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
  return response.json();
}

/**
 * User account class for managing user information

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change