JSDoc @param - 引用另一个模块中的参考类

Question

我有两个Node模块。在模块A中，我有以下定义：

/**
 * HTTP Client
 * @module src/http/client
 */
/**
 * A HTTP Client
 * @alias src/http/client
 */
class HTTPClient {
   [... class def with documented methods etc]
}
module.exports = HTTPClient

现在在B模块中，我想说第一个构造函数参数应该是HTTPClient类型。因此，我尝试了以下内容：

class PackageFactory {
    /**
     * @param {module:src/http/client} httpClient - the HTTPClient instance
     */
    constructor(httpClient) {
       this._httpClient = httpClient
    }
}

我也尝试了几种变化，但都没有成功。在B模块中，httpClient始终为“任意”类型。我需要改变什么才能在B模块中看到HTTPClient类成员？

- newBee

---

你可以尝试使用 @param {module:src/http/client~HTTPClient} httpClient 吗？ - zero298

似乎没有任何效果。或者这可能是我正在使用的 Visual Studio Code 没有正确显示的问题？ - newBee

Answer 1

解决方案比我想象的要简单。无需包含模块路径（也称为长名称）或任何其他内容。

const HTTPClient = require('../http/client')
class PackageFactory {
    /**
     * @param {HTTPClient} httpClient - the HTTPClient instance that shall be used to make requests
     */
    constructor(httpClient) {
       this._httpClient = httpClient
    }
}

- newBee

---

这种方法的问题在于，你会收到关于未使用HTTPClient的警告。 - JohnFlux

Answer 2

为了避免任何代码检查工具报告的“HTTPClient未使用”错误，您可以在@param字段本身中导入该类。这使得文档阅读起来有点困难，但是您可以在设计时获得自动完成，这是一个不错的权衡。

请注意，您可以与tsconfig.json的compilerOptions.paths选项结合使用，以创建别名，使那些文档导入看起来更好。

class PackageFactory {
    /**
     * @param {import('../http/client')} httpClient - the HTTPClient instance that shall be used to make requests
     */
    constructor(httpClient) {
       this._httpClient = httpClient
    }
}

- Aurelien Ribon