Repository navigation
Support ~ namespace qualifier in JS Doc type positions #47199
Description
Activity
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- changed the title
[-]Using jsdoc @param with scoped type definition ignores the fact that param is optional[/-][+]Support `~` namespace qualifier in JS Doc type positions[/+]on Jan 4, 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!
Bug Report
I'm using
tscto create a.d.tsfile 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:
Outputted
.d.tsfile:🙁 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).