Repository navigation
Support import types in JSDoc links #43950
Description
Bug Report
🔎 Search Terms
- JSDoc
- link / see
🕗 Version & Regression Information
4.3.0-dev.20210503
💻 Code
For some JavaScript:
// foo.js
export class Foo {}// index.js
/**
* {@link import('./foo').Foo Foo}
*
* @param {import('./foo').Foo} foo
*/
function withFoo(foo) { }🙁 Actual behavior
The parameter type is resolved but the @link is not
🙂 Expected behavior
Both links should be resolved
Activity
olee commentedon Nov 15, 2021
Same issue for me - this is especially annoying, because TS and eslint regard type imports which are only used for JSDoc as unused and will request to remove those imports.
marcelocra commentedon May 13, 2023
As a workaround, you could use typedef with an import, pointing the link to it:
Not great, as "go to definition" will take you to this typedef instead of the main one, but at least the correct type is shown when hovering.
jespertheend commentedon May 13, 2023
That will cause
TheTypeto be exported twice though (#46011). I usually just end up not linking at all in this situation, because I'd rather not have duplicate entries in my autocomplete list.ethanresnick commentedon Nov 20, 2023
I would really love to see this too.
Linking to other symbols in JSDoc comments is super useful, but adding the
import typeat the top-level (to get jump-to-definition for that symbol) triggers eslint'sno-unused-varrule.Using the
no-undefined-typesrule fromeslint-plugin-jsdoccan solve that (it'll mark the import as used for Eslint), but that rule creates the risk of a non-type-only import that's only used in a JSDoc comment being marked as used, which could lead to unnecessary/unexpected side effects in theverbatimModuleSyntaxworld.@link/@see.Typescript's
organizeImportslanguage feature will automatically remove the import, even if it's referenced in a JSDoc comment.Today, I think the best solution is to manually alias the import to start with an
_, and configure eslint to not flag variables as unused if they start with an_, but that aliasing is kinda annoying. The import will also still get removed by TS'organizeImportseven with the alias.optyler commentedon Dec 5, 2023
I think my old issue is similar to this one...
I was trying to
@linka function from an imported module fromnode_modulePer
jsdocdocumentation this should be possibleI was expecting that these comments link to the function in
node_module/date-fns/formatbut they just render as iskravetsone commentedon Jul 18, 2024
+1
Why i should import it in top of the module for simple JSDoc link?
esperecyan commentedon Aug 1, 2025
In my legacy ESLint setup with .eslintrc.json, I used import type plus
eslint-plugin-unused-importsandeslint-plugin-jsdocto preserve type-only imports referenced only in{@link }comments. After migrating to Flat Config (eslint.config.ts),unused-imports/no-unused-importsnow treats those imports as unused and removes them, ignoring their usage in TSDoc comments.This makes the issue more urgent in my setup, and I’m really hoping it can be resolved soon.
perf: run unused-import checks natively in oxlint (Comfy-Org#19067)