VS 代码中的 JSDoc 用于使用模块类型记录功能答案

【问题标题】：JSDoc in VS code for documenting function with module's typeVS 代码中的 JSDoc 用于使用模块类型记录功能
【发布时间】：2017-12-21 19:44:16
【问题描述】：

我想记录在另一个模块中编写的函数，该模块使用 http.ClientRequest 类型参数。我想要这样的东西，但它不起作用：

/**
* @param {ClientRequest} req 
*/

function setToken(req) {
}

我也试过@param {http.ClientRequest}，但没用。

更新： 基本上我通过import http from "http"; 导入所需的模块解决了这个问题。但是，我不想导入它，因为这个模块没有使用http module，而是提供了帮助函数。

【问题讨论】：

标签： javascript node.js visual-studio-code jsdoc

【解决方案1】：

从 IGx89 改进答案后，我得到了一个没有 typedef 的较短变体。当我一次引用另一个模块时，我更喜欢这个变体：

/**
* @param {import('http').ClientRequest} req 
*/
function setToken(req) {

}

但是，如果您需要从另一个模块中引用某些类型，那么带有长路径变体的 typedef 看起来会更短。

【讨论】：

【解决方案2】：

将以下内容添加到文件顶部：

/** @typedef {import('http').ClientRequest} ClientRequest */

我自己也遇到过同样的问题（虽然是关于我自己应用程序中的一个模块），并且也很难找到解决方案。通过阅读 TypeScript GitHub 存储库中的这个问题，我最终弄清楚了上述语法：https://github.com/Microsoft/TypeScript/issues/14377

【讨论】：

这是理想的...在文件顶部声明它是有意义的。谢谢你的救命稻草！

【解决方案3】：

它不起作用，因为它是 JSDoc 不知道的自定义类型。您必须使用@typedef 设置您自己的定义。

/**
* A number, or a string containing a number.
* @typedef {(number|string)} NumberLike
*/

/**
* Set the magic number.
* @param {NumberLike} x - The magic number.
*/
function setMagicNumber(x) {
}

在JSDoc typedef tag definition examples上查看完整示例

我用 JSDoc 3.5.3 做了一个对我有用的例子

/** @typedef {ClientRequest} TestReq */

/**
* @param {TestReq} req 
*/
function setToken(req) {
}

JSDoc output image

【讨论】：

在 NodeJs 中有一个名为 http 的模块。它有 http.ClientRequest 接口。
我不知道你的意思，但类型取决于 javascript 类型定义（字符串、数字、对象......）。所以JSDoc不可能知道类型“http.ClientRequest”。您需要为其自定义类型定义。也许您可以在使用 @param {Object} 时解决问题，但这会使其非常通用。