JSDoc support for destructured parameters

[kitsonk]

TypeScript Version: 2.0.3

Code

interface Foo {
    /**
     * A bar value
     */
    bar?: string;
}

/**
 * A function
 *
 * @param foo A param
 * @param { bar } Another param
 * @param bar Another param
 */
function foo(foo: string, { bar }: Foo): void {
    bar;
    foo;
}

foo('bar', { bar: 'play' });

Expected behavior:

Intellisense for the second argument, or the second argument properties.

Actual behavior:

No way of providing a description for the destructured elements of a destructured parameter.

[steph643]

+1
As a JS developer relying on destructuring for function parameters, this issue generates a lot of false "problems" when mixing parameters with and without default values.

[eduardobcastro]

This does not work on version 1.21.1

/** Class representing a user. */
module.exports = class User {
  /**
  * Create a User.
  * @param {object} user
  * @param {string} user.id - The user id in uuid format
  * @param {string} user.name - The user name
  * @param {string} user.email - The user email
  * @param {string} user.password - The user password
  */
  constructor({id, name, email, password}) {
    this.id = id
    this.name = name
    this.email = email
    this.password = password
  }
}

[hellos3b]

Also an issue when functions return an interface

interface Returns {
  /** This object contains a getter that returns itself */
  get: (key: string) => string;
}

const buildObject = (): Returns => ({
  get: key => key
})

// shows jsdoc description when hovering over "obj1.get"
const obj1 = buildObject();
const a = obj1.get("key")

// Only shows signature "const get: (key: string) => string"
const {get} = buildObject();
const b = get("key");

[zachhardesty7]

Also would really like to have the comments made in my interface show on hover of destructured variables. In the mean time, has anybody found a workaround? I destructure code all over the place and can't figure out how to document the variables.

[mesqueeb]

@edbentley
I'm very interested in your last commit concerning this issue.

What did you mean with

Note we could move the jsdoc comments to this interface.

I'm experiencing the same issue where destructured function params don't show the JSDoc comment. : S

[edbentley]

@mesqueeb I just meant that it wasn't worth moving the existing JSDoc comments to the interface since they still won't show.

[eps1lon]

Would like to see this implemented for the basic case:

interface Options {
  /**
   * description
   */
  param?: string;
}
const options: Options = {};
// `param` has no JSDOC
const { param }  = options

Any pointers where the implementation should happen (and tests)?

Should the description also be carried over if the destructured value has a default value e.g.

// Should `param` have the description of `options.param`?
const { param = 'someDefaultValue' }  = options

[saschanaz]

Any pointers where the implementation should happen (and tests)?

Maybe https://github.com/microsoft/TypeScript/blob/master/src/services/jsDoc.ts ?

[rohit-gohri]

Looking at this issue a year after subscribing to it, I feel the requirement doesn't make sense if we look at the implications of supporting this. Because if this is implemented then wouldn't it also mean carrying over descriptions at every assignment?

Since this

const { param }  = options;

is equivalent to

const param = options.param;

If the description is really important then maybe something like Nominal Types can be used so a reference to the original type is still around if not it's description, eg.:

TS Playground link

[MarcosAtApprentice]

This seems related to this weird issue I'm having with type inference on object destructuring. Posted about it here: #44730 (comment)

[PoulBak]

Is JSDoc dead? This has not been fixed in almost 6 years.

[steida]

So effectively, JSDoc shall not be used to document TypeScript code. Fortunately, we can use markdown.

Eg. "### Example with ```ts"

A weird thing is, that "@link" can be used. "@param and @example" not.