Typescript: JsDoc annotations don't play well with arguments destructuring

[KtorZ]

Code

As stated in this comment (I am afraid this won't be seen since the issue is closed, hence the issue):

/**
 * @param {Object} args 
 * @param {string} args.prop1
 * @param {string} args.prop2
 */
function patate({ prop1, prop2 }) {

}

Expected behavior:

Type-checking this using --allowJs and --checkJs shouldn't result in an error but rather apply the right type-annotations to the both properties.

Actual behavior:
The compiler raises the following error:

error TS8024: JSDoc '@param' tag has name 'args', but there is no parameter with that name.

[andy-ms]

Might be fixed by #18832 that would allow us to do the matching positionally.

[mhegazy]

Duplicate of #7429

[typescript-bot]

Automatically closing this issue for housekeeping purposes. The issue labels indicate that it is unactionable at the moment or has already been addressed.

[KtorZ]

@mhegazy You mentioned earlier that this was a duplicate of #7429 and #7429 is now labeled "fixed". Nevertheless, the bug I described earlier is still present in 2.6.2 and the latest nightly (2.7.0-dev.20180112).

:/ Any idea ?

[mhegazy]

you are right, the fix in #7429 did not address this case as well.

[que-etc]

@KtorZ

There is a workaround which we are using in our project. I don't really know if it works for you, as the following approach can't be used with function declarations, but anyway:

/**
 * @type {function({prop1: string, prop2: string}): void}
 */
const patate = ({prop1, prop2}) => {
    // ...
}

/**
 * This definition works as well.
 * @type {(args: {prop1: string, prop2: string}) => void}
 */
const patate = ({prop1, prop2}) => {
    // ...
}

It's certainly not as legible as describing every property in it's own @param annotation, though you can move object's definition to its own @typedef.

And there is one major pitfall of which you should know. TypeScript currently has a bug (#22080) which allows to invoke former function without any arguments:

/**
 * @type {function({prop: string}): void}
 */
const func = ({prop}) => {
    // ...
};

// TypeScript should raise an error for the following
// line ('Expect 1 argument, but got 0'), but unfortunately it doesn't. 
func();

I hope it helps.

[KtorZ]

Thanks. For now I've been simply doing the destructuring in the function body and it works fine, though I'd rather cut off this extra line... Perhaps I can apply your solution in some cases :/

/**
 * @param {Object} args 
 * @param {string} args.prop1
 * @param {string} args.prop2
 */
function patate(args) {
  const { prop1, prop2 } = args;
} 

[ghost]

We definitely need this. If I can help somehow let me know guys.

[Madd0g]

I've seen multiple discussions about this and people seem to be pleased it's working, but with version 2.7.2 even the simple version doesn't work for me:

/**
 * @param {Object} args 
 * @param {string} args.prop1
 * @param {string} args.prop2
 */
function patate(args) {
  const { prop1, prop2 } = args;
} 

With allowJs and checkJs, I get JSDoc '@param' tag has name 'prop1', but is no parameter with that name.

Which TS version should have the dotted parameters notation supported (with no desctructuring in the the parameters)?

[KtorZ]

This "hack" used to work for me in (2.7.0-dev.20180112) So I'd say somewhere between 2.7.0 & 2.7.1

[sandersn]

@Madd0g I can't repro your bug with master. Can you try typescript@next? I've fixed a lot of bugs in jsdoc recently, so it's likely that it was recently fixed.

[Madd0g]

Huh, interesting, some of my code has this non-standard syntax for optional/required, it's really weird because every google search I do now specifies a different syntax for optional/required, so I don't know how I settled on this back when I wrote it:

/**
 * @param {!object} args 
 * @param {!string} args.prop1
 * @param {?string} args.prop2
 */
function patate(args) {
  const { prop1, prop2 } = args;
} 

With this syntax typescript@next still gives that error, but since I can't find any docs that mention this syntax, I guess it's just wrong?

Yes, the code from my previous comment works perfectly for me in typescript@next.

Thanks.

[sandersn]

@Madd0g yep, jsdoc is a giant mess. Typescript actually understands that optional and required syntax, it just doesn’t expect it in conjunction with the multi-line literal type syntax. In other words, the parser is looking for exactly object on the first line, not !object.

Note that required doesn’t actually mean anything to the compiler, since structNullChecks: true means that everything is required by default and strictNullChecks: false means the compiler allows null/undefined everywhere.

You might want to open a separate bug for your case, actually.

[steph643]

As far as I can tell, the issue is still partially there (VSCode 1.23.1).

See the number type becoming any and the missing param comment:

Strangely enough, if you omit the Object, you get the param comment back (but not the type):

[steph643]

VSCode 1.24, released a few hours ago, is much better at this:

• param types are now parsed correctly,
• it seems param comments are still missing.

[sandersn]

@steph643 can you file a separate bug for the param comments?

[steph643]

@sandersn : done, see above.