Repository navigation
Support ~ namespace qualifier in JS Doc type positions #47199
Description
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).
Activity
RyanCavanaugh commentedon Jan 4, 2022
This is unsupported for a number of reasons -- we parse a type name in that position, so the name would be
Test.myCallbacknotTest~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[-]Using jsdoc @param with scoped type definition ignores the fact that param is optional[/-][+]Support `~` namespace qualifier in JS Doc type positions[/+]djipco commentedon Jan 5, 2022
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
anyis 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 usinganyfor an unknown type) when necessary.Also, instead of using
any, why not use thefunctiontype in such a case (or perhaps a call signature)? After all, the@callbackblock 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!