Bug: no-unused-vars does not account for references in JsDoc #8902
Comments
|
Is there any chance to re-consider this ? I get that @bradzacher thinks "JSDoc is not real code" but the typescript compiler actually disagrees with this. It is a shame that |
|
@matthieusieben: ts-eslint models the "TypeScript language" part of |
|
Thanks for the detailed explanation. These tools are so complicated to get working (e.g. one would assume that typescript-eslint is on par feature wise with typescript), I find it a missed opportunity. But that's just me (and probably a few other from those other issues). Thanks for your work anyways. |
JSDoc is a very, very loosely defined spec for how it works. It's not even really a spec - it's more of a convention. There's a lot of ambiguity in it and TS does not enforce that you write it in a specific way - it just loosely handles the comments as best it can. When we parse TS code we use TS's parser. Code is well defined with a grammar and there's little ambiguity (there is technically some but the TS parser handles and hides that ambiguity) and we get one concrete AST representation for the file. We don't need to worry about problems like "what if someone provides two return type annotations?" Cos you cannot provide two return type annotations on a function that's a syntax error to even try it. OTOH JSDoc comments do not have the same concrete representation. /**
* @returns {string}
* @returns {number}
* @return {boolean}
* @return {null}
*/What does it mean? Who knows really - the interpretation is left up to the consumer. So you can see how this gets complicated - what do we do here? Well we have to research and understand exactly how JSDoc is handled by TS internally so that we can model that exact same behaviour. That means every TS release we also need to review TS's JSDoc handling again to determine if anything changed. It's a huge maintenance burden for us as volunteer maintainers. So instead we have chosen to not handled JSDoc at all and instead, as Josh mentioned, we tell people to use I.e. instead of us trying to understand JSDoc ourselves whilst we're working to understand TS - we leave that responsibility to a separate project which has the knowledge and resources that can do that. This separation of concerns creates a higher quality result with less stress/burden on any one group and is a core tenet of how the ESLint ecosystem has evolved and grown. I definitely understand the reason behind wanting this - but ultimately it's a very niche usecase within the TypeScript ecosystem. A very, very small fraction of people annotate JSDoc this way. Which is why it's not worth us as bandwidth-limited, volunteer maintainers to dedicate time to supporting this. The cost:value ratio isn't there for us when |
Before You File a Bug Report Please Confirm You Have Done The Following...
Playground Link
not-applicable
Repro Code
ESLint Config
tsconfig
{ "compilerOptions": { } }Expected Result
Foois used in JsDoc, and correctly references the original definition in vs-code (alt + click goes to the definition)Actual Result
@typescript-eslint/no-unused-vars considers this is an unused var, while typescript does not.
Additional Info
Note that if the reference is removed from the JSdoc, typescript starts complaining about an unused var as well.
The text was updated successfully, but these errors were encountered: