JSDoc Cheatsheet

Best Practices

Guidelines for writing effective JSDoc documentation

Consistency

Maintain consistent formatting across your documentation

Syntax:

Use consistent formatting and style

Example:

// Always use the same format for similar tags
// Good: @param {string} name - User name
// Good: @param {number} age - User age

Completeness

Ensure all public functions, classes, and modules are documented

Syntax:

Document all public APIs

Example:

// Document all parameters, return values, and exceptions
// Include examples for complex functions

Clarity

Use clear, descriptive language that explains purpose and behavior

Syntax:

Write clear, concise descriptions

Example:

// Good: Calculates user age from birth date
// Bad: Does age stuff

Type Safety

Include detailed type information to improve code reliability

Syntax:

Always specify types for parameters and returns

Example:

// Always include types
@param {string|null} name - User name or null
@returns {Promise<User>} Promise resolving to user object

Examples

Provide practical examples showing how to use the code

Syntax:

Include usage examples for complex functions

Example:

/**
 * @example
 * // Basic usage
 * const result = myFunction('input');
 * 
 * @example
 * // Advanced usage
 * const result = myFunction('input', { option: true });
 */