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.