Блог

Я работаю над относительно большим проектом, и я хочу добавить JSDoc в свои классы и файлы, чтобы упростить его разработку. У меня есть функция получения для моего класса / объекта «Конфигурация», которая возвращает свой экземпляр объекта «SQLRegistry», который устанавливается позже по цепочке.

 //configuration.js

/**
 * @returns {SQLRegistry} registry
 */
getRegistry() {
    return this._registry;
}
  

 //sqlRegistry.js
const Configuration = require('./configuration');

class SQLRegistry {
    //other code
}
  

К сожалению, в VS Code с IntelliSense / ESLint он выдает ошибку, в которой говорится, что он не может найти класс ‘SQLRegistry’. В любой другой ситуации я бы просто импортировал sqlRegistry.js в configuration.js , но в этой ситуации я не могу (потому что sqlRegistry зависит от configuration.js , как вы можете видеть выше).

Есть ли какой-нибудь комментарий JSDoc, который я могу поместить в начало файла, который сообщает ему о чтении sqlRegistry.js , чтобы он узнал о классе SQLRegistry? Например, что-то вроде:

 /**
 * @include {@link ./sqlRegistry.js}
 */
  

Ваша гипотеза @include {@link ./sqlRegistry.js} была очень близка в принципе.

Фактический способ написать это в интерпретации синтаксиса JSDoc в TypeScript таков

 /**
 * @returns {import('./sqlRegistry.js')} registry
 */
getRegistry() {
    return this._registry;
}
  

Обратите внимание, что именно TypeScript фактически поддерживает основные функции JavaScript VS Code, такие как вывод типов, а не ESLint

Этот синтаксис, import('module-specifier') в позиции типа, известен как типы импорта, не путать с импортом только типа и был введен в TypeScript 2.9.

Это не специфичная функция JSDoc, а скорее из TypeScript.

Языковая служба TypeScript распознает синтаксис в местах комментариев JSDoc, где ожидается тип. Обратите внимание, что в официальном руководстве по TypeScript указано, что

Вы также можете импортировать объявления из других файлов, используя типы импорта. Этот синтаксис зависит от TypeScript и отличается от стандарта JSDoc: