An alternative @overload syntax for JSDoc

[rdking]

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.

[fatcerberus]

I was under the impression that the main purpose of @overload was to allow you to have separate documentation (summary text, parameter descriptions, etc.) for each overload, like you can already do in TS. Consolidating them like this would defeat the purpose.

[rdking]

Not true, or at least not with the way I envision it functioning when generating documentation. The presence of 2 or more @overload tags would have the effect of producing a function definition for each @overload supplied. The params given in the @overload tag would be used as a filter in the list of params within the jsdoc comment. The net effect of the above would be documented as if the example below didn't cause the latter to replace the former:

/**
 * @function share
 * @param {object} inst
 * @param {function} klass
 * @param {object} members
 * @returns {object}
 */
/**
 * @function share
 * @param {object} inst
 * @param {object} members
 * @returns {undefined}
 */

If it is actually beneficial for there to be completely separate documentation for each overload (usually unlikely), then that could be satisfied by having separate comment blocks with only 1 @overload tag allowed. However, that case of a single tag would not allow a function definition to be specified with it. In that case, the example in my OP would be equivalent to:

/**
 * @override
 * @function share
 * @param {object} inst
 * @param {function} klass
 * @param {object} members
 * @returns {object}
 */
/**
 * @override
 * @function share
 * @param {object} inst
 * @param {object} members
 * @returns {undefined}
 */