JSDoc - Quick Reference
When NOT to Use This Skill
- TypeScript projects - Use the
jsdoc-tsdocskill 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_docswith technology:jsdocfor 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} |