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
claude-dev-suite