Support `~` namespace qualifier in JS Doc type positions

[djipco]

Bug Report

I'm using tsc to create a .d.ts file from jsdoc comments in my JavaScript source files. When I scope a custom type definition using the "~" character, if the parameter is optional, it will not be in the outputted .d.ts.

According to jsdoc documentation, this is the correct way to scope a callback to a specific class.

💻 Code

JavaScript source:

class Test {

  /**
   * @callback Test~myCallback
   * @param {string} [name] Event name
   */

  /**
   * @method
   * @param {string} [event] Event name.
   * @param {Test~myCallback} [callback] The callback
   */
  removeListener(event, callback) {
  
  }

}

Outputted .d.ts file:

declare class Test {
  removeListener(event?: string, callback: any): void;
}

🙁 Actual behaviour

The output renders "callback" as if mandatory. This is invalid as a mandatory parameter cannot follow an optional one. Also, the type is "any", event though I defined a custom type.

🙂 Expected behaviour

The "callback" parameter should be optional as specified in the source JavaScript. The type should be "Test~myCallback" (or however TypeScript deals with these).

[RyanCavanaugh]

This is unsupported for a number of reasons -- we parse a type name in that position, so the name would be Test.myCallback not Test~myCallback (honestly the first I've ever heard of someone using that syntax, jsdoc website aside). But TS doesn't support class-scoped types yet either, so the type declared in that position isn't going to work through any syntax

[djipco]

Thanks for the explanation. It's clearer now.

As a follow up, I would like to humbly formulate a suggestion. In the example above, per your explanation, I understand why any  is used for the second parameter. However, this parameter should still be optional. Having a mandatory parameter follow an optional one halts compilation. Valid jsdoc should not generate invalid declaration files. It does make sense, however, to have those files degrade gracefully (such as using any for an unknown type) when necessary.

Also, instead of using any, why not use the function type in such a case (or perhaps a call signature)? After all, the @callback block describes the function's parameters (caveat: I'm not a TypeScript developer so what I'm suggesting might be rubbish).

Anyway, as far as documenting the API for my library, this is the only missing piece when using --emitDeclarationOnly.

Thanks for your work on this. Cheers!