JSDoc：来自文字的 Typedef

Question

让我们考虑以下代码，一个 return 具有两个函数的对象的函数：

/**
 * Create a something
 * @returns {object} Something
 */
function createSomething() {
  return {
    /**
     * Foo!
     * @returns {string}
     */
    foo() { return 'foo';},

    /**
     * Bar!
     * @returns {string}
     */
    bar() { return 'bar';}
  };
}

调用此方法时，即使 return 类型只是 object，IDE:s 等 WebStorm 也会从 returned 文字推断类型，因此输入 createSomething(). 将建议成员 foo 和 bar。

但是，假设我需要将此对象传递给其他函数。为了让这些函数明白这是一个"something"，我想@typedef它，所以我做了以下操作：

/**
 * @typedef {object} Something
 */

/**
 * Create a something
 * @returns {Something} Something
 */
function createSomething() {
  return {
    /**
     * Foo!
     * @returns {string}
     */
    foo() { return 'foo';},

    /**
     * Bar!
     * @returns {string}
     */
    bar() { return 'bar';}
  };
}

现在我们有了 createSomething() 中 return 对象的类型。但是，因为 return 类型是明确声明的，IDE 将 NOT 自动从 returned 值中推断出任何成员，所以我们现在有没有任何已知成员的定义类型。

我当然可以在 @typedef 中手动输入每个成员作为 @property，如下所示：

/**
 * @typedef {object} Something
 * @property {function} foo
 * @property {function} bar
 */

然而，这意味着每当我从 Something 对象中添加或删除任何成员时，都必须手动保持 typedef 同步。

我尝试将 @typedef 放在 createSomething() 中 return 语句的正上方，希望它能向 JSDoc 和 IDE 提示 typedef 具有成员在以下文字中定义，但无济于事 - @typedef {object} 似乎总是被视为除了明确声明的 @property 之外没有其他成员。

有没有办法让 IDE 从 returned 文字自动推断成员，同时为 returned 对象定义类型？基本上我想要与使用 ES6 时发生的情况相同类 - 它自动成为一个所有方法都是成员的类型。

Answer 1

您可以在对象初始化器之前为此使用 @lends 标记，如下所示：

function createSomething() {
  return /** @lends Something# */ {
    // properties
  }
}

/** @param {Something} s */
function f(s) {}

WebStorm 理解这一点。请注意 # 在 @lends 中的姓名后签名。

JSDoc：来自文字的 Typedef

JSDoc: Typedef from literal

javascript

intellij-idea

jsdoc

webstorm