JSDoc ...rest parameter syntax cannot support tuple types

Bug Report

🔎 Search Terms

jsdoc rest tuple

🕗 Version & Regression Information

• This is the behavior in every version I tried, and I reviewed the FAQ for entries about JSDoc

⏯ Playground Link

Playground link with relevant code

💻 Code

/**
 * @callback CBFunction
 * @param {number} n
 * @param {string} s
 */

// Desired outcome:
// typedef CBCaller = (...args: Parameters<CBFunction>) => void

/**
 * @param {...Parameters<CBFunction>} args
 */
function f(...args) {
  console.log(args);
}

🙁 Actual behavior

See Playground link: on .d.ts tab, the output is declare function f(...args: [number, string][]): void;, an array-of-tuples. Generally, JSDoc syntax treats {...X} args as args: X[].

🙂 Expected behavior

TS-flavored JSDoc should be able to express any type that TS can express.

[sandersn]

TS’ jsdoc doesn’t currently have a good way to match any rest parameter to a @param tag. The code you wrote is unfortunately already used by closure type syntax in jsdoc, so this

/**
 * @param {...Parameters<CBFunction>} args
 */
function f(...args)

Is like writing this:

function f(...args: Parameters<CBFunction>[])

even if it weren’t used, everything inside {} is supposed to be a type.

We need an alternate proposal. One possibility is to add the … on the parameter name:

/**
 * @param {Parameters<CBFunction>} ...args
 */
function f(...args)

This might conflict with existing jsdoc, but I don’t think it does off the top of my head. And I think it would be possible to enforce the usual rules on ...: eg that it can only occur once, at the end of a parameter list.

[thw0rted]

tsd-jsdoc does not currently use the TS compiler, though they have been thinking about it for a while. I believe the answer to your question is, they only support a subset of all the JSDoc constructs that the TS compiler does.