Why does VS Code show wrong JSDoc for array items props?

Question

JSDoc on VS Code is displaying props as an object instead of an array.

You can test it yourself by hovering your mouse on the function name in this codesanbox snippet.

According to JSDoc documentation, it should be able to document:

a prop value via object destructuring: @param {string} employee.name
array items props, like so: @param {string} employees[].name

I couldn't find any limitation regarding JSDoc support on VS Code docs either.

Would that be an issue on VS Code, JSDoc or the way I'm documenting my JavaScript functions?

Note: I'm aware there's a workaround for this using @typedef like below, but I'm more interested in knowing why the documentation doesn't work as I expect.

/**
 * A standard user
 * @typedef {Object} User
 * @property {number} id - The unique ID for the user.
 * @property {string} name - The user name.
 */

/**
 * Foo bar.
 * @param {Object} props - The props.
 * @param {User[]} props.users - A list of users.
 */
function foo(props) {

}

user_1244884 · Answer

I'm not too sure as to why exactly the [] notation isn't properly recognised. I have found this alternative (without resorting to @typedef) which seems to be close to what you want:

/**
 * Foo bar.
 * @param {Object} props - The props.
 * @param {Array<{id:number, name:string}>} props.users - A list of users.
 */
function foo(props) {

}

JSDoc supports Closure Compiler's syntax for defining array and object types.

So we can use Array<> and record notations as defined here:
https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System

Couple of screenshots:

I admit this doesn't look like VS Code does understand that notation:

However when you start accessing the props.users elements it looks better:

Why does VS Code show wrong JSDoc for array items props?

1 Answers