Attach Documentation to Labeled Tuple Elements

[harrysolovay]

Suggestion

I often find myself describing function params as labeled tuples. A simple example:

type AddArgs = [a: number, b: number];
function add(...[a, b]: AddArgs): number {
  return a + b;
}

Unfortunately, this approach prevents us from attaching tsdocs to the params. The following does not work :/

type AddArgs = [a: number, b: number];
/**
 * @param a the first number
 * @param b the second number
 */
function add(...[a, b]: AddArgs): number {
  return a + b;
}

I propose that one be able to attach tsdocs to labeled tuple elements, just as one does to object keys.

type AddArgs = [
  /** the first number */
  a: number,
  /** the second number */
  b: number,
];

I also propose that––when spread in place of function params––these tsdocs are treated as if they were the result of @param annotations on the function declaration.

🔍 Search Terms

Documentation, labeled, tuple, elements, tsdocs, signature

✅ Viability Checklist

My suggestion meets these guidelines:

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

[harrysolovay]

Linking to #41165 for posterity

[sirius16]

I hope this gets done, it would be very helpful in writing overload functions were vargs/args would be a union of labeled tuples.