An alternative @overload syntax for JSDoc

Suggestion

🔍 Search Terms

jsdoc
function
overload

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

Here's an alternative thought on the syntax that could satisfy PR #52474 without causing parser issues mentioned in PR #52577. What if overload simply allowed you to declare a method signature? For instance:

/**
 * @overload { (inst, klass, members) => object }
 * @overload { (inst, members) => undefined }
 * @param {object} inst
 * @param {function} klass
 * @param {object} members
 * @returns {object|undefined}
 */
function share(inst, klass, members) {}

This should be both easy to parse, and satisfy the user's needs while allowing for minimally redundant documentation, all in a single comment.

Start by reviewing the proposed JSDoc examples and the referenced PRs #52474 and #52577, especially the parser concerns. Done means the alternative @overload syntax has an agreed implementation path that addresses those concerns without changing runtime behavior.