Bug: no-unused-vars does not account for references in JsDoc about typescript-eslint HOT 5 CLOSED

Duplicate of #5017, #6967, #7944, #8258.

from typescript-eslint.

@matthieusieben: ts-eslint models the "TypeScript language" part of typescript. There's also a "JavaScript linting" part of typescript which includes JSDoc and lots of heuristic-based inference to make "idiomatic JS" work without any rewriting. We never explicitly have support for this part. Similarly, TypeScript has cross-module checking features, but we don't, because it's delegated to eslint-plugin-import. For JSDoc, you would want to use eslint-plugin-jsdoc instead.

from typescript-eslint.

JSDoc is not real code

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.
For example this is a valid annotation:

/**
 * @returns {string}
 * @returns {number}
 * @return {boolean}
 * @return {null}
 */

What does it mean? Who knows really - the interpretation is left up to the consumer.
For TS it will error on this comment and mark the last 3 as an error with 'returns' tag already specified. However TS emits a JSDoc AST for this and that AST contains FOUR JSDocReturnTag nodes.

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 eslint-plugin-jsdoc which is built in its own way with its own rules and parser for handling JSDoc.

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 eslint-plugin-jsdoc is there for people to opt-in to support these usecases.

from typescript-eslint.

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 typescript-eslint does not follow the conventions abopted typescript...

from typescript-eslint.

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.

from typescript-eslint.