Last updated
Example: Function with Error Handling
// Input function:
function parseJSON(jsonString) {
if (typeof jsonString !== 'string') {
throw new TypeError('Input must be a string');
}
try {
return JSON.parse(jsonString);
} catch (e) {
throw new SyntaxError(`Invalid JSON: ${e.message}`);
}
}
// Generated JSDoc:
/**
* Parses a JSON string and returns the resulting JavaScript value.
*
* @param {string} jsonString - The JSON string to parse.
* @returns {*} The JavaScript value represented by the JSON string.
* @throws {TypeError} If the input is not a string.
* @throws {SyntaxError} If the string is not valid JSON.
*
* @example
* parseJSON('{"name": "Alice"}'); // → { name: 'Alice' }
* parseJSON('[1, 2, 3]'); // → [1, 2, 3]
*/
function parseJSON(jsonString) { ... }
Example: Async Function
// Input function:
async function fetchUser(userId) {
const response = await fetch(`/api/users/${userId}`);
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}
return response.json();
}
// Generated JSDoc:
/**
* Fetches a user by their ID from the API.
*
* @async
* @param {number|string} userId - The unique identifier of the user to fetch.
* @returns {Promise<Object>} A promise that resolves to the user object.
* @throws {Error} If the HTTP request fails or returns a non-OK status.
*
* @example
* const user = await fetchUser(42);
* console.log(user.name);
*/
async function fetchUser(userId) { ... }
Example: Class Documentation
// Input class:
class EventEmitter {
constructor() {
this.events = {};
}
on(event, listener) {
if (!this.events[event]) this.events[event] = [];
this.events[event].push(listener);
return this;
}
emit(event, ...args) {
if (this.events[event]) {
this.events[event].forEach(l => l(...args));
}
}
off(event, listener) {
if (this.events[event]) {
this.events[event] = this.events[event].filter(l => l !== listener);
}
}
}
// Generated JSDoc:
/**
* A simple event emitter for subscribing to and publishing events.
*
* @class
* @example
* const emitter = new EventEmitter();
* emitter.on('data', (value) => console.log(value));
* emitter.emit('data', 42);
*/
class EventEmitter {
/**
* Creates a new EventEmitter instance.
*/
constructor() {
/**
* @private
* @type {Object.<string, Function[]>}
*/
this.events = {};
}
/**
* Registers a listener for the specified event.
*
* @param {string} event - The name of the event to listen for.
* @param {Function} listener - The callback function to invoke when the event fires.
* @returns {EventEmitter} The current instance (for chaining).
*/
on(event, listener) { ... }
/**
* Emits an event, invoking all registered listeners with the provided arguments.
*
* @param {string} event - The name of the event to emit.
* @param {...*} args - Arguments to pass to each listener.
* @returns {void}
*/
emit(event, ...args) { ... }
/**
* Removes a specific listener from the specified event.
*
* @param {string} event - The name of the event.
* @param {Function} listener - The listener function to remove.
* @returns {void}
*/
off(event, listener) { ... }
}
Example: TypeScript Function
// Input TypeScript:
function findById<T extends { id: number }>(items: T[], id: number): T | undefined {
return items.find(item => item.id === id);
}
// Generated JSDoc:
/**
* Finds an item in an array by its numeric ID property.
*
* @template T - The type of items in the array. Must have a numeric 'id' property.
* @param {T[]} items - The array of items to search.
* @param {number} id - The ID to search for.
* @returns {T | undefined} The matching item, or undefined if not found.
*
* @example
* const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
* findById(users, 1); // → { id: 1, name: 'Alice' }
* findById(users, 99); // → undefined
*/
function findById<T extends { id: number }>(items: T[], id: number): T | undefined { ... }
Example: Module Documentation
// Input module (utils.js):
export function debounce(fn, delay) { ... }
export function throttle(fn, limit) { ... }
export const sleep = ms => new Promise(r => setTimeout(r, ms));
// Generated JSDoc:
/**
* @module utils
* @description Utility functions for async operations and performance optimization.
*/
/**
* Creates a debounced version of a function that delays invocation until
* after the specified wait time has elapsed since the last call.
*
* @param {Function} fn - The function to debounce.
* @param {number} delay - The number of milliseconds to delay.
* @returns {Function} The debounced function.
*
* @example
* const debouncedSearch = debounce(search, 300);
* input.addEventListener('input', debouncedSearch);
*/
export function debounce(fn, delay) { ... }
/**
* Creates a throttled version of a function that invokes at most once
* per the specified time limit.
*
* @param {Function} fn - The function to throttle.
* @param {number} limit - The minimum time in milliseconds between invocations.
* @returns {Function} The throttled function.
*/
export function throttle(fn, limit) { ... }
/**
* Returns a promise that resolves after the specified number of milliseconds.
*
* @param {number} ms - The number of milliseconds to wait.
* @returns {Promise<void>} A promise that resolves after the delay.
*
* @example
* await sleep(1000); // wait 1 second
*/
export const sleep = ms => new Promise(r => setTimeout(r, ms));
JSDoc Tags Reference
- @param {type} name - description — documents a function parameter
- @returns {type} description — documents the return value
- @throws {ErrorType} description — documents thrown exceptions
- @async — marks function as asynchronous
- @template T — documents a generic type parameter
- @example — provides a usage example
- @deprecated — marks as deprecated with migration note
- @since version — documents when the API was added
- @private / @public / @protected — access modifiers
- @type {type} — documents a variable's type
- @typedef — defines a custom type
- @module — documents a module
Paste your JavaScript or TypeScript code to generate JSDoc comments automatically. Review the generated descriptions and replace placeholder text with meaningful documentation specific to your implementation.
Example: Simple Function
// Input function:
function calculateTax(price, taxRate) {
return price * (taxRate / 100);
}
// Generated JSDoc:
/**
* Calculates the tax amount for a given price and tax rate.
*
* @param {number} price - The base price before tax.
* @param {number} taxRate - The tax rate as a percentage (e.g., 8.5 for 8.5%).
* @returns {number} The calculated tax amount.
*/
function calculateTax(price, taxRate) {
return price * (taxRate / 100);
}