Optional function parameter with any return type in jsdoc is treated as required

[TimvdLippe]

TypeScript Version: 4.0.0-dev.20200512

Search Terms: jsdoc, declaration, optional

Code

clazz.js:

export class Clazz {
  /**
   * @param {string=} optionalParam
   * @param {function():*=} optionalFunctionDeclaration
   */
  method(optionalParam, optionalFunctionDeclaration) {}
}

tsconfig.json:

{
  "compilerOptions": {
    "outDir": "lib",
    "declaration": true,
    "allowJs": true,
    "checkJs": true
  },
  "files": [
    "clazz.js"
  ]
}

Expected behavior:
The emitted declaration file is:

export class Clazz {
    /**
     * @param {string=} optionalParam
     * @param {function():*=} optionalFunctionDeclaration
     */
    method(optionalParam?: string | undefined, optionalFunctionDeclaration?: (() => any) | undefined): void;
}

Actual behavior:

> tsc --version && tsc -p tsconfig.json

Version 4.0.0-dev.20200512
vararg.js:6:25 - error TS1016: A required parameter cannot follow an optional parameter.

6   method(optionalParam, optionalFunctionDeclaration) {}
                          ~~~~~~~~~~~~~~~~~~~~~~~~~~~


Found 1 error.

Note that the return type is * which is any in jsdoc. If we use a different return type, TS will compile successfully. For example, if we use ? as return type the following is emitted:

export class Clazz {
    /**
     * @param {string=} optionalParam
     * @param {function():?=} optionalFunctionDeclaration
     */
    method(optionalParam?: string | undefined, optionalFunctionDeclaration?: (() => unknown) | undefined): void;
}

Playground Link:

Related Issues: #37703

[sandersn]

@weswigham you might be interested in this too. Looks like your fix didn't catch everything? I'll investigate more when I get to this bug.

[weswigham]

The error is on the js input, not the declaration file output, so it's an issue in typechecking jsdoc optional parameters somewhere. I imagine the postfix = is being parsed after the *, rather than after the whole function type (so it parses like a nonsense "optional return")? At least that'd cause an error like this.

[sandersn]

The tokeniser actually produces function, (, ), :, *= for this input, so the parser has a separate code path for *=, which always produces "optional all-type". The correct fix is probably to produce an all-type, put back an = as the next token, and continue parsing. But I'll have to check how feasible that is.

[sandersn]

I grepped our user code tests for ):*= and didn't find any instances -- but we locked to an old commit of chrome-devtools years ago. I assume this occurrence came from a recent commit of chrome-devtools?

[TimvdLippe]

Yes you are using quite an old version. The references are here: https://source.chromium.org/search?q=%22:*%3D%22%20f:devtools-frontend%20-f:out%2F&sq=&ss=chromium&originalUrl=https:%2F%2Fcs.chromium.org%2F

[sandersn]

Our test of an old version of devtools-frontend is an odd one for us. It has so many transitional patterns that expose bugs in our JS-handling code that we'd lose with an updated code base. On the other hand, it's likely that fewer and fewer people use those patterns -- probably we should just update and allow support for the old way to bit-rot.

In any case, handling this case in the scanner is the correct way to do it. I have a fix up at #39457.