IntelliSense with types of JSDoc

[egamma]

From @anseki on March 8, 2016 4:25

I tried this:

/**
 * @param {string} param1 - Normal
 * @param {string|number|boolean} param2 - Multiple types
 * @param {null} param3 - (I know this is strange param.)
 * @param {string|number|null} param4 - Multiple types includes `null`
 * @param {Object} param5 - Object type
 * @param {Array} param6 - Array type
 * @param {jQuery} param7 - Another type
 * @param {MyClass} param8 - Another type
 * @param {string|number|Array} param9 - Multiple types includes `Array`
 * @param {?string} param10 - Nullable type
 * @param {string} [param11] - Optional
 * @returns {?string} result
 */
function fnc(param1, param2, param3, param4, param5, param6,
    param7, param8, param9, param10, param11) {
  return param11;
}

fnc();

• param3: any, param4: any, param6: any, param7: any, param8: any, param9: any
• param10: string

It seems that:

• The type of @param that includes null, Array, and other classes other than Object are shown as any.
• The optional params are shown with ?, but nullable params and returns are shown with nothing.

I hope that the specified types are shown even if that is null, Array, or unknown type such as jQuery or MyClass. And nullable params are shown like optional params.

Copied from original issue: microsoft/vscode#3802

[egamma]

moving to TypeScript

[RyanCavanaugh]

As for nullability, this is by design. Nullable parameters aren't the same as optional, and T | null won't be valid syntax until nullable types become available in TypeScript.

For Array we need to special-case this (we expected to see Array<T>)

[DanielRosenwasser]

@RyanCavanaugh I think the special case should be general enough for all generic types - perhaps instantiating with with any for all type arguments.

[Thaina]

I too think null is not type. It is value. You need to set type as {boolean | number} not {true | number}. Same go for null, you could set it as string or any

As for nullable it is {?any}

For {Array} is should be just like {[]}

[anseki]

Yes I know null or undefined are value.
But some style guide such as Google JavaScript Style Guide specifies null in JSDoc to indicate the param that might be multiple type and null.
If the param accepts something type and null, it can be {?somethingType}. But if it accepts more types and null, no notation for "multiple && nullable".

[anseki]

Sorry, I don't understand the mechanism of IntelliSense. Is showing specified text as type difficult? even if that is unknown type such as jQuery or DOM element or MyClass.

[anseki]

I think that this issue is solved if IntelliSense parses @typedef or @class. Those tags might be able to deceive IntelliSense. (It make also a source code dirty.)
Or, as I said, it is solved if IntelliSense shows specified text as type.

I think that null is needed by current version of JSDoc to indicate an optional param that is not positioned at the end of params list because It don't have syntax to indicate that now. http://usejsdoc.org/tags-type.html
Then, some style guides such as Google specify null.
Also, types such as Array, jQuery, DOM element or MyClass are typically used in JS.
Those should be shown. Because JSDoc is used for documentation or some guide, JSDoc is not a tool to check syntax like debugger.
We don't want to write @class and something for jQuery in to all source code.

[mhegazy]

With nullable types in, we should add logic to handle ?T and !T.