Preserve comments with object destructuring assignment

Search Terms

object destructuring assignment, comment

Suggestion

interface MyInterface {
    /**
     * I am x
     */
    x : number;
    /**
     * I am y
     */
    y : number;
}
declare const myInterface : MyInterface;
const {x, y} = myInterface;

/**
 * Expected tooltip to have comment,
 * > I am x
 * 
 * Actual: No comment
 */
x;
/**
 * Expected tooltip to have comment,
 * > I am y
 * 
 * Actual: No comment
 */
y;

/**
 * Expected tooltip to have comment,
 * > I am x
 * 
 * Actual:
 * Tooltip has comment,
 * > I am x
 */
myInterface.x;

/**
 * Expected tooltip to have comment,
 * > I am y
 * 
 * Actual:
 * Tooltip has comment,
 * > I am y
 */
myInterface.y;

/**
 * I am z
 */
const z = 1;

/**
 * Expected tooltip to have comment,
 * > I am z
 * 
 * Actual:
 * Tooltip has comment,
 * > I am z
 */
z;

Playground

Use Cases

I came across this idea after writing code like this,

function foo (
  {
    somePropertyA,
    somePropertyB,
    somePropertyC,
  } : SomeObject
) {
  /* Use these properties */
}

And I was hazy on the details of what each property was for. So, I hovered my cursor over the variables somePropertyA, somePropertyB, somePropertyC and noticed there were no comments.

I had to go to the declaration of somePropertyA, somePropertyB, somePropertyC and look at each property individually.

---

At the moment, the way to get comments is to just do,

function foo (
  o : SomeObject
) {
  /* Use these properties */
}

Then the tooltip for o.somePropertyA, o.somePropertyB, o.somePropertyC will have comments

Examples

See above suggestion

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, etc.)
• This feature would agree with the rest of TypeScript’s Design Goals.

[Arcath]

Let’s take react hooks as an example.

I have a hook called useForm that returns an object. The react way would be to do this:

const MyComponent: React.FC = () => {
  const {bind, onSubmit} = useForm({name: ''})

  // Rest of component
}

In this situation any JSDoc comments for bind or onSubmit are not passed on from the output of useForm to the destructured variables. I would argue that even if I use {onSubmit: formSubmit} the documentation for onSubmit still applies.

If the typings are passed over why is the documentation not?

I have an example on the playground that shows what I mean.

I get that these are the same:

const x = someObject.x
const {x} = someObject

but I would have said in both instances I would expect the documentation to copy over. x is still someObject.x and unless I redfine it in some way its still the same.

[ab-pm]

There should be a way to document/annotate the destructured variables themselves. It should work with the JsDoc comment syntax shown in this Stack Overflow answer:

interface Example {
    /** interface property doc */
    foo: string;
}
const example: Example = {foo: 'bar'};

const {
    /** variable doc */
    foo
} = example;

console.log(foo);

When hovering over the foo variable in the last line, I would expect to see the “variable doc” in the IntelliSense variable description.