Trackback to #7200 which proposes the same change but I guess didn't have enough information to kick off the process?

Thanks for the proposal. This seems like it might be a good idea (at least as an option), although it might be tricky to handle the edge cases correctly, because JSDoc comments don't have a well-defined variable scope as far as I know.

import Foo from 'foo';

{
  const Foo = somethingElse;
  /**
   * @param {Foo} what does this mean?
   */
  function x() {}
}

Would it be appropriate to survey how this is implemented in various JSDoc-consuming toolsets and see if there's a consensus? Just as a data point, VSCode treats the JSDoc param references as being scoped where they're declared:

/**
 * This is at global scope
 */
function Foo(){}

function Bar(){
    /**
     * This is function scoped
     */
    class Foo{
    }

    /**
     * Baz the catz
     * @param {Foo} catz 
     */
    function Baz(catz) {}
}

The @param ref above gives a tooltip of "This is function scoped" when you mouse over the {Foo} (as IMHO you'd probably expect).

As a maintainer of closure-compiler, I can pipe in here. The scope of a JSDoc comment is exactly where it occurs. From the above example:

import Foo from 'foo';

{
  const Foo = somethingElse;
  /**
   * @param {Foo} what does this mean? -- it means somethingElse. No ambiguity at all.
   */
  function x() {}
}

Hello, what's the status of this? It would be great to have it.

As much as I would like to see this warning go away, importing a module that isn't used is more of a dirty fix for VSCode. It also has it's own issues. For example, performing an import angular from 'angular'; would cause AngularJS to load and start processing the DOM, even if you only plan on using the module as a JSDoc reference.

It could create an out of order module loading, therefore the eslint warning/error is a good one.

PS: You can use typings.d.ts in your workspace root and VSCode will use it in conjunction with JSDoc. It's another VSCode workaround, but a less intrusive one.

See: microsoft/TypeScript#14377 for a more permanent fix.

JSDoc is comments; variables aren't "used" by comments, only by code. If this support is added (I don't think it should be; it belongs in a separate JSDoc-related rule, just like jsx vars being marked as used are in an eslint-plugin-react rule), I hope it's at least in a separate option.

The above comments make good points. Maybe it would make more sense to have a directive specific to JSDoc that allows it to resolve imports that are used in docs, without affecting the actual code? Would something like /* import Foo from 'foo' */ be any more useful to JSDoc than a simple /* global Foo */ (which of course works today)?

Would something like /* import Foo from 'foo' / be any more useful to JSDoc than a simple / global Foo */ (which of course works today)?

No - the code is not unused. The import is actually needed to order dependencies correctly. And additionally - it's not global. During module references, closure-compiler will update the type nodes as well and the import is required to do that.

For example, performing an import angular from 'angular'; would cause AngularJS to load and start processing the DOM, even if you only plan on using the module as a JSDoc reference.

This is a case where an alternative scheme should be used. If you just want to mention angular as a type for documentation but don't need dependency ordering or a true type reference, you would want to skip this and use angular as a global.

@ChadKillingsworth Documentation isn't used by the compiler. When you load a module, you're actively loading all its dependencies and whatever initialization it wants into runtime. This means more objects into memory and whatever else is going on with the module import process.

Using a runtime command for the sake of a transpile process (closure-compiler) isn't appropriate. That is, unless you want the transpile process to remove the import line which doesn't sound safe at all. That's why it should be in comments.

Microsoft's Typescript handles the same issue by using triple slashes (///) which are comments that tell the transpiler how to load references and types: http://www.typescriptlang.org/docs/handbook/triple-slash-directives.html

That's why the argument about handling this issue within Microsoft's Salsa (JS Typechecking) leans to using a comment based import. microsoft/TypeScript#14377

But back to the original reported issue at hand, the question is why is @thw0rted even importing a module without referencing it in code in the first place? If he's doing it only to workaround an issue with Microsoft's Salsa typechecking (which I'm guessing he is), he should follow the issue I posted before. If he's using it for Closure transpiling, he should file the issue there.

Documentation isn't used by the compiler.

This is simply not true for Closure Compiler. It's used heavily.

But back to the original reported issue at hand, the question is why is @thw0rted even importing a module without referencing it in code in the first place?

He is referencing the code in type annotations. In cases where you want to reference a module type without actually importing it, Closure-Compiler supports the syntax:

/** @type {./path/to/module.propName} */

However, use of that syntax inappropriately can cause files to be ordered incorrectly when compiling.

If a compiler uses documentation, that’s fine, but then the compiler is obligated to actually use documentation. If something declared only in comments needs additional information for the compiler to be able to work with it, that info needs to also be in a comment.

If Closure Compiler can’t do this, it seems like a bug in that project; not something eslint needs to handle.

Just to settle the debate, back when I filed this issue I was using eslint, but as a VS Code plugin, so I cared about both eslint and Salsa -- ideally, any solution would work with both of them. I've since moved that codebase to Typescript but I think I still have one or two places where this "kind" of problem comes up.

I think from eslint's perspective, specifically, you can always resolve the issue with a simple /* global Foo */, instead of having to import Foo from "foo". This prevents import side-effects, as @clshortfuse points out. VS Code / Salsa can probably figure things out without an import, as long as there's a reference to Foo elsewhere in your workspace; worst case, there's always the option of a global ambient typing declaration. I'll let the rest of you figure out how Closure Compiler should handle things, as I haven't used it.

@ChadKillingsworth My reference to compiler was the javascript runtime compiler (ie: V8). You're talking about use with closure-compiler which is a transpiler than that converts code down to the actual JS runtime compiler. The documentation is ignored there.

Still, as you said, Closure Compiler has syntax for referencing types via comments. So in reality, you shouldn't be using import if you use Closure, and instead use the syntax you provided. VSCode (ie: Microsoft Typescript Salsa) doesn't, so the workaround is adding a module import into the runtime code. Once Microsoft adds the ability to reference a type from an external file without adding a module import, this eslint warning/error would go away.

Hi all, this just came up again -- I'm upgrading to Webpack 4.x and discovering that type-checking in the editor would be super helpful. Previously, I just declared

module.exports = { ...tons of webpack }

then ran the build tool and hoped the config was valid. There's a typings file for Webpack, of course, which means that there's an interface definition that lays out exactly what's valid in that assignment... if I can explicitly set its type. But to do that, I need to import the config-object interface from the module, and of course that makes eslint unhappy.

This isn't a deal-breaker, since I don't have e.g. hooks to reject commits that cause eslint errors, but I'd still really appreciate a way to either a) import something only for docs, or b) mark an import as "actually used even though eslint says it's not", on a one-off basis.

@thw0rted

I'd still really appreciate a way to either a) import something only for docs, or b) mark an import as "actually used even though eslint says it's not", on a one-off basis.

You can accomplish (b) using inline disable comments. Example: Place // eslint-disable-line no-unused-vars on the same line as the import to avoid getting a report for that case. See our documentation for more information.

Thanks, I actually found this while poking around solving other issues -- for some reason I can't get eslint-disable-line or eslint-disable-next-line to work (maybe it's my eslint version?) but using a "disable" before and an "enable" after does seem to do the trick. In the long run, (a) would be nice to have, but I'm not sure how to avoid side-effects...

In the long run, (a) would be nice to have, but I'm not sure how to avoid side-effects...

Agreed, just wanted to say option b was possible now in case you didn't know. (Not sure why the line disable comments didn't work, though...)

@platinumazure, I ran into same issue with type declarations. Option (b) simply disables unused imports check at all. And if we remove type declaration usage from the file, we want to see warning about unused import. But ESLint tells us that everything is Ok.

VSCode (and Typescript) now supports

/** @typedef {import('../foo/bar').baz} baz */

So you don't have to perform unused imports anymore.

Thanks, @clshortfuse , I'm tracking via #14377 and #22592. I don't know why I didn't see the links to the former in earlier comments, but it makes sense.

A thought occurs to me, though: if this syntax is unique to tsc / VS Code / Salsa / whatever, won't eslint choke on the vendor-specific syntax? Has the TS team worked with eslint to ensure that code written using the new import() syntax is going to pass eslint?

@thw0rted Yes. I work with an eslint rule that requires valid jsdoc and this new syntax works fine.

@ChadKillingsworth do you have any sense of whether Closure might consider adding a notion like the VSCode/Typescript workaround mentioned above (/** @typedef ... */ but not typedef since Closure uses that to mean something else)? We have a very large JS codebase that's Closure compiler compiled and we have to use no-unused-var: "off" because of the "unused imports" needed for Closure, which is highly annoying.

Are you not able to do a single-line eslint-disable comment? That's what I've been using though now that I'm thinking of it, I'll probably go ahead and switch to import().

The single-line eslint disable comment doesn't work so well if you have multiple imports on one line:

import { Foo, Bar, Baz } from './example.js';

export class Test {
  /**
   * @param {!Foo} foo
   */
  constructor(foo) {
    /** @const */
    this._foo = foo;
    /** @const */
    this._bar = new Bar();
  }
}

Adding the single-line eslint disable comment to line 1 causes the unused Baz to not be detected. Obviously changing this to use multi-line imports with a per-symbol single-line disable comment would work:

import {
  Bar,
  Baz,
  Foo,  // eslint-disable-line
} from './one.js';

but that is going to require a large scale refactor and a code convention change. Not impossible, but unideal.

@timdawborn can't you use @typedef to import types only? (sort of like import type ... from ... in Flow)

import { Bar, Baz } from './example.js';

/** @typedef {import('./example.js').Foo} Foo */

export class Test {
  /**
   * @param {!Foo} foo
   */
  constructor(foo) {
    /** @const */
    this._foo = foo;
    /** @const */
    this._bar = new Bar();
  }
}

@LinusU @typedef has a different meaning and purpose in Closure: https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler#typedef-type

$ java -jar closure-compiler.jar -W VERBOSE --language_in ECMASCRIPT6_STRICT --language_out ECMASCRIPT5_STRICT --js one.js --js test.js --js_output_file /dev/null
test.js:2: WARNING - Bad type annotation. Unknown type import
/** @typedef {import('./one.js').Foo} Foo */
              ^

test.js:2: WARNING - Bad type annotation. expected closing } See https://github.com/google/closure-compiler/wiki/Bad-Type-Annotation for more information.
/** @typedef {import('./one.js').Foo} Foo */
                    ^

test.js:4: WARNING - Misplaced typedef annotation. @typedef does not make sense on a class declaration.
export class Test {
       ^^^^^^^^^^^^

0 error(s), 3 warning(s), 85.7% typed

aha, good to know 👍

Perhaps an issue should be filed on closure compiler to support that syntax - that seems like it’d both solve this issue and also be consistent with typescript’s usage of jsdoc.

google/closure-compiler#3041 discusses some of this.

Workaround for this issue: // eslint-disable-line no-unused-vars

import Foo from "foo"; // eslint-disable-line no-unused-vars
/**
* @param {Foo} f
*/
function bar(f){ return f.baz; }

Thanks for the suggestion. As of yesterday, we have decided to officially end-of-life JSDoc support in ESLint. All JSDoc features are now deprecated and we won't be fixing bugs or making any further improvements to those features.

We are recommending that people transition over to use the eslint-plugin-jsdoc plugin instead of the built-in rules in ESLint.

Thanks for understanding and we apologize for any inconvenience.