JSDoc type reference doesn't skip leading asterisk

[golopot]

TypeScript Version: typescript@3.6.0-dev.20190704

Search Terms:
checkjs
jsdoc
multi-line
multiline
Code

/**
 * @returns {
 *   | 'a'
 *   | 'b'
 *   | 'c'
 * } - this type is parsed as `any`.
 */
function f() {
  return true;
}

Expected behavior:
Error on incompatible return type.
Actual behavior:
No error. The jsdoc return type is parsed as any.
Playground Link:
Not available.

[orta]

This isn't a real type in TypeScript terms - are you trying to describe something which returns 'a' or 'b' or 'c'?

If so, you probably want:

/**
 * @returns  'a' | 'b' | 'c
 */
function f() {
  return true;
}

playground

The { and } are used for interfaces, a union doesn't need them

[golopot]

@orta
That is not true. The { and } are JSDoc's syntax, used as delimiter for type expressions. ref. A valid jsdoc comment looks like this: /** @param {string} - some descriptions. */.

[golopot]

cc @sandersn

[sandersn]

Yep, this is a real bug! The prefix-pipe syntax obscures it a bit. Here's a simpler repro:

/**
 * @returns {
 *  'a'}
 */
function f() {
  return true;
}

Note that subsequent asterisks are fine, it's just leading asterisk before the type gets started:

/**
 * @returns {
   'a'
 * | 'b' }
 */
function f() {
  return true;
}

That's because type parsing uses Typescript rules, which have a hacky exemption for asterisks inside jsdoc. But it's clearly not reliable. I'm pretty sure it's because all the tests we added are for object types, which we expected to be formatted like this:

/**
 * @returns {{
 *   a: number
 * }}
 */

Here, the type starts before the newline-asterisk sequence.