TypeScript recently introduced the @link tag in JSDoc comments. The documentation is here.
However, @link only generates an actual link if the TypeScript compiler knows the link target. In other words, whatever I link to must either be declared within the same file or imported. This isn't always the case, however. Take this (made-up) example:
wheel.ts
/** A wheel for use with a {@link Car}. */
export interface Wheel {
// ...
}
In this example, the JSDoc comment in wheel.ts references a type Car that is defined in a separate file, car.ts. Because wheel.ts doesn't import car.ts, TypeScript doesn't know what @link Car points to. As a result, it can't display a proper link for Car when displaying the documentation in VS Code:
So my question is: How can I tell TypeScript where to find the definition of Car?
I've tried the following approaches:
1. Regular import
Adding import { Car } from './car'; to the top of wheel.ts solves the problem and creates an actual link to Car (note how "Car" has turned blue now):
However, it leads to the TypeScript error "'Car' is declared but its value is never read. (6133)" on the import line. TypeScript doesn't seem to consider the @link tag an actual usage of the imported type.
I can add // @ts-ignore above the import to tell TypeScript to ignore the error. But that seems pretty ugly to me.
2. Type import
Instead of a regular import, I can use a type import: import type { Car } from './car';. The result is the same: The link works, but I get a TypeScript error.
3. Inline import
TypeScript supports type imports within JSDoc comments. So I tried the following syntax:
/** A wheel for use with a {@link import("./car").Car}. */
However, it seems that TypeScript doesn't evaluate imports within links:
4. Typedef comment
I tried importing the type as follows:
/** @typedef {import('./car').Car} Car */
/** A wheel for use with a {@link Car}. */
export interface Wheel {
// ...
}
However, this didn't create a link, either.