JS Doc @param Object Bug

[mjbvz]

From @fleck on April 6, 2018 15:7

• VSCode Version: 1.22.0
• OS Version: MacOS 10.13.3

Steps to Reproduce:
Create the following file:

/**
 * Create a notification.
 * @param {string} options.heading Text for the header.
 * @param {string} [options.href] Where the primary button links to. The image will also be linked
 * to this href if an image is included.
 * @param {string} [options.imageUrl] Optional image url.
 * @param {string} [options.body] Optional text for the body.
 * @param {string} [options.buttonText] Text of the primary button.
 * @param {string} [options.secondButtonText] Text of the secondary button.
 * @param {string} [options.secondHref] Href of secondary button.
 * @param {string} [type] Add error styling by passing 'Error' for this parameter.
 * @param {object} options Object properties are interpolated into the error template.
 */
const Notification = (options, type = 'default') => {
};

export default Notification;

import the previous file and hover over Notification();

import Notification from './Notification';

Notification();

The signature of the function param 'object' is wrongly classified as any, but the descriptions below are correct.

Move options object description to the first position

/**
 * Create a notification.
 * @param {object} options Object properties are interpolated into the error template.
 * @param {string} options.heading Text for the header.
 * @param {string} [options.href] Where the primary button links to. The image will also be linked
 * to this href if an image is included.
 * @param {string} [options.imageUrl] Optional image url.
 * @param {string} [options.body] Optional text for the body.
 * @param {string} [options.buttonText] Text of the primary button.
 * @param {string} [options.secondButtonText] Text of the secondary button.
 * @param {string} [options.secondHref] Href of secondary button.
 * @param {string} [type] Add error styling by passing 'Error' for this parameter.
 */
const Notification = (options, type = 'default') => {
};

export default Notification;

and now hover over Notification(); and you'll see that the signature is correct, but the descriptions are now wrong.

Does this issue occur when all extensions are disabled?: Yes

Copied from original issue: microsoft/vscode#47333

[mjbvz]

Not sure if the first example (with the out of order param member declaration) is a valid jsdoc or not

In the second case, we lose the main options comment though, along with all the @param tags for the members

[sandersn]

@mjbvz

1. No, at least according to usejsdoc and typescript. The second example is correct.
2. I'm not sure how inline object types flow through the language service to Code. On the parse tree, at least, all the comments are on their individual @param tags, so it's probably a matter of combining their descriptions correctly for display. @Andy-MS might know more about this, or I can go looking to find out.