Preserve comments with object destructuring assignment

[AnyhowStep]

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.

[AnyhowStep]

I also noticed that the following does not get me comments,

interface MyInterface {
    /**
     * I am x
     */
    x : number;
    /**
     * I am y
     */
    y : number;
}

function foo (
    {
        /**
         * Additional comments about x
         */
        x,
        /**
         * Additional comments about y
         */
        y,
    } : MyInterface
) {
    /**
     * Expected tooltip to have comment,
     * > Additional comments aout x
     * > I am x
     * 
     * Actual: No comment
     */
    x;
    /**
     * Expected tooltip to have comment,
     * > Additional comments aout y
     * > I am y
     * 
     * Actual: No comment
     */
    y;
}

Playground

[RyanCavanaugh]

I disagree that it's expected. If you wrote the desugared version

const x = someObj.x;

there would (I think?) be no expectation of the comments transferring over.

[AnyhowStep]

I guess you make a good point.

It's just that I saw object destructuring assignment as sugar for reading someObject.x, even if it's not really that.

What about Additional comments about x?

---

I feel like I don't have the same expectation of the desugared version because it's possible for the variable to have a different name from the property.

But with the sugared version, they'd have the same name.

Unless they do const {x:someOtherIdentifier} = someObj;, then I guess I don't have that expectation.

Hmmm...

I guess my request now is to have comments carry over if the variable has the same name as the property. And to not carry over if they're different.

I hope I'm not the only one that would like this =(

I feel like if they have the same name, they probably have the same "overall meaning"; like what the variable is describing

[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.

[woolson]

Same issue, mybe new feature request.

---

Description

Property comments and type display on mouse hover myMac.editor, but only type shows on mouse hover destructure property.

Example

/** My Mac App Gallery */
interface MyMac {
  /** My Editor */
  editor: string
  /** My Browser */
  browser: string
}

const myNewMac: MyMac = {
  /** My Editor */
  editor: 'VS Code',
  /** My browser */
  browser: 'Edge',
};

myNewMac.editor;
myNewMac.browser;

const { editor } = myNewMac;
console.log('My editor name:', editor);

Screenshot

[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.

[yolilufei]

is there any progress, please?