VSCode only renders JSDoc link to another file when symbol is imported

user_4371525 0
Viewed 1778

I'm trying to use JSDoc @link annotation to refer to a class on a different file but VSCode doesn't recognize it and the tooltip is rendered as plain text.

I've found a workaround which is to import the symbol into my file. However, I don't want to import something just so it can appear in the docs.

Screen capture

How do I make it work?

TDLR

Links within the same file work correctly. The problem is only with cross-file links, but there's no relevant reference to the subject in VSCode's docs for the @link directive.

I'm running:

  • VSCode 1.58.2
  • TypeScript 4.3.5
visual-studio-code typescript jsdoc
2 Answers

Isn't this exactly how you'd expect it to work? If you add a link to a symbol, VS Code (or any IDE, really) needs to know what symbol exactly you mean.

If they'd just have to guess the symbol, not only would they have to go through all possible typed files, there would also be classes because e.g. 20 of your dependencies (or even 20 files within a single dependency) all create an export interface Options for example.

You might be able to get away with using import('module').Export as type.

Alternatively, you can use a type-only import, added in TypeScript 3.5:

import type { SomeType } from 'some-module';

// Works fine, since we're only using the type
type UsingTheType = Partial<SomeType>;

// Errors, because we didn't import the actual value
// (assuming it should be a value anyway, e.g. a class)
const someType = new SomeType();

If you look at the transpiled code, you'll notice that this doesn't actually result in an import/require. Type-only don't actually get imported at runtime, it only imports the types at compile-time.

TypeScript should do the same trick if you use a regular import where values aren't used, but this is more explicit.

user_142745970

The accepted answer to this question is correct. You can always fix this by using a type-only import. However, sometimes the imported types are not used anywhere else in the file, so, assuming you're using ESLint, you'll probably get a @typescript-eslint/no-unused-vars error/warning. I'm currently disabling the rule for such imports, which is far from ideal obviously. I think the ideal fix would be one that allows importing it within the TSDoc somehow.

user_101408070
Related