JSDoc for Overloaded Functions

Documenting Function Overloads

TypeScript function overloads allow a function to accept different parameter types and return different types. Each overload signature should be documented separately.

Example Signature

function parse(input: string): JsonObject;
function parse(input: Buffer): JsonObject;
function parse(input: string | Buffer, encoding?: string): JsonObject;

Generated JSDoc

/**
 * Parses a JSON string into an object.
 *
 * @param {string} input - A JSON-encoded string.
 * @returns {JsonObject} The parsed JSON object.
 */

/**
 * Parses a JSON buffer into an object.
 *
 * @param {Buffer} input - A buffer containing JSON data.
 * @returns {JsonObject} The parsed JSON object.
 */

/**
 * Parses JSON from either a string or buffer.
 *
 * @param {string | Buffer} input - The JSON input.
 * @param {string} [encoding] - The buffer encoding. Defaults to "utf-8".
 * @returns {JsonObject} The parsed JSON object.
 * @throws {SyntaxError} If the input is not valid JSON.
 */

Documentation Strategy

1. Document each overload: Each signature gets its own comment block
2. Implementation signature: The final (implementation) signature can have a comprehensive comment
3. Be specific: Each overload comment should describe behavior specific to that parameter type

TSDoc Approach

TSDoc recommends documenting only the overload signatures (not the implementation), because the implementation signature is not visible to consumers:

/**
 * Parses a JSON string.
 * @param input - A JSON-encoded string.
 */
function parse(input: string): JsonObject;
/**
 * Parses a JSON buffer.
 * @param input - A buffer containing JSON data.
 */
function parse(input: Buffer): JsonObject;

When to Use Overloads vs Union Types

Document overloads when the return type depends on the input type. Use union parameters when the behavior is identical regardless of input type.