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

Issue

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.

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

Solution

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.

Answered By - Kelvin Schoofs