TypeScript introdujo recientemente la etiqueta @link en los comentarios de JSDoc. La documentación está aquí .

Sin embargo, @link solo genera un enlace real si el compilador de TypeScript conoce el destino del enlace. En otras palabras, todo lo que enlace debe declararse dentro del mismo archivo o importarse. Sin embargo, este no es siempre el caso. Tome este ejemplo (inventado):

rueda.ts

 /** A wheel for use with a {@link Car}. */ export interface Wheel { // ... }

En este ejemplo, el comentario JSDoc en wheel.ts hace referencia a un tipo Car que se define en un archivo independiente, car.ts . Debido a que wheel.ts no importa car.ts , TypeScript no sabe a qué @link Car . Como resultado, no puede mostrar un enlace adecuado para Car cuando se muestra la documentación en VS Code:

Entonces mi pregunta es: ¿Cómo puedo decirle a TypeScript dónde encontrar la definición de Car ?

He intentado los siguientes enfoques:

1. Importación regular

Agregando import { Car } from './car'; hasta la parte superior de wheel.ts resuelve el problema y crea un enlace real a Car (observe cómo "Car" se ha vuelto azul ahora):

Sin embargo, genera el error de TypeScript "Se declara 'Car' pero nunca se lee su valor. (6133)" en la línea de importación. TypeScript no parece considerar la etiqueta @link como un uso real del tipo importado.

Puedo agregar // @ts-ignore arriba de la importación para decirle a TypeScript que ignore el error. Pero eso me parece bastante feo.

2. Tipo de importación

En lugar de una importación regular, puedo usar una importación de tipo: import type { Car } from './car'; . El resultado es el mismo: el enlace funciona, pero aparece un error de TypeScript.

3. Importación en línea

TypeScript admite la importación de tipos dentro de los comentarios de JSDoc . Así que probé la siguiente sintaxis:

 /** A wheel for use with a {@link import("./car").Car}. */

Sin embargo, parece que TypeScript no evalúa las importaciones dentro de los enlaces:

4. Comentario Typedef

Intenté importar el tipo de la siguiente manera:

 /** @typedef {import('./car').Car} Car */ /** A wheel for use with a {@link Car}. */ export interface Wheel { // ... }

Sin embargo, esto tampoco creó un vínculo.