我应该在 JSDoc 中使用与 @param 兼容的类吗？答案

【问题标题】：Should I use a compatible class with @param in JSDoc?我应该在 JSDoc 中使用与 @param 兼容的类吗？
【发布时间】：2020-11-13 13:41:10
【问题描述】：

我的 Python API 返回一个 JSON 对象，例如：

{
    a: 1,
    b: 'hi'
}

我在客户端也有一个类：

class Sth {
    constructor() {
        this.a = null;
        this.b = null;
    }
}

我收到一个对象并将其不加修改地传递给函数。我应该像这样使用@param，而不是简单的@param {*}吗？

/**
 * @param {Sth} sth Is Sth appropriate here?
 */
function f(sth) {
    // Do sth
}

【问题讨论】：

【解决方案1】：

与外部/第三方资源的交互通常由extern 键入。如果您在本地转换代码，即：获取并使用数据创建实例，那么您的解决方案是正确的：类就足够了。但是，如果您要获取数据并将其传递给构造函数，您可能希望在 externs 中定义一个类型。

在开始使用外部人员时，我发现 closure debugger 非常有用。

【讨论】：

【解决方案2】：

是的，这很合适。 JSDocs 会将类视为一种类型。如果 Sth 类在与您的函数相同的文件中不可用，您可能需要在该文件中定义 JSDoc 类型，例如/** @typedef {import("./path/to/your/class/file.js").Sth} Sth*/

如果您可以避免@param {*}，您通常应该避免，因为拥有更多类型信息总是更好！

【讨论】：