When generating declaration file from a JavaScript file with JSDoc, description of named parameters should be copied to description of the properties in the generated object type

🔍 Search Terms

• copy description from jsdoc to properties
• named parameter description

✅ Viability Checklist

• 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 isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

Currently, the description that follows a @param options.field Description of field does not copy Description of field to the corresponding property in the generated object type. But TypeScript should've done that.

Related: https://github.com/microsoft/TypeScript/issues/57328

📃 Motivating Example

JavaScript file:

/**
 * Do something
 * @param {Object} options Description of options
 * @param {String} options.foo Description of foo
 * @param {Number} options.bar Description of bar
 */
export function doSomething(options) {
  console.log(options)
}

tsconfig:

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "declaration": true,
    "emitDeclarationOnly": true,
    "strict": true,
    "strictNullChecks": true,
    "module": "ES2022",
    "target": "ES2022"
  }
}

Expected behavior:

/**
 * Do something
 * @param {Object} options Description of options
 * @param {String} options.foo Description of foo
 * @param {Number} options.bar Description of bar
 */
export function doSomething(options: {
    /** Description of foo **/
    foo: string;
    /** Description of bar **/
    bar: number;
}): void;

Actual behavior:

/**
 * Do something
 * @param {Object} options Description of options
 * @param {String} options.foo Description of foo
 * @param {Number} options.bar Description of bar
 */
export function doSomething(options: {
    foo: string;
    bar: number;
}): void;

💻 Use Cases

1. What do you want to use this for? Generate TypeScript declarations with working intellisense
2. What shortcomings exist with current approaches? Intellisense ignores descriptions of named parameter
3. What workarounds are you using in the meantime? None

Reproduce the issue with the JavaScript example and tsconfig shown in the report, then trace TypeScript's JSDoc handling during declaration emission; no source files or tests are named in the payload. Done means generated declarations retain the descriptions for foo and bar as property comments and a regression test covers the case.