如何在 Visual Studio Intellisense 中记录 JavaScript 配置对象

Question

我已经使用 Visual Studio 的 JavaScript Intellisense functionality 有一段时间了，对它为标准 API 提供建议的能力非常满意，但我发现我无法让 Visual Studio 理解配置对象（即单个具有多个可选或必需属性作为函数参数的对象）。

official JSDoc syntax 建议如果一个参数应该有属性，你可以为每个参数创建一个单独的@param 行并使用点表示法：

/**
 * @param {Object} config
 * @param {String} config.name
 * @param {Number} config.gold
 */
function do_it(config) { ... }

但是，Visual Studio 无法识别这一点 - 它将 config、config.name 和 config.gold 呈现为三个单独的顶级参数。

更糟糕的是，方法主体中的 AutoComplete 功能也无法识别参数，更不用说它们的类型了：

在 Visual Studio 中似乎更接近的唯一解决方案是编写带有适当文档（@constructor 和 @property 标记）的从未调用的构造函数，这使我编写了很多死代码，也违背了JavaScript 的无类心态（这是我首先使用配置对象的原因）。它甚至不让我写配置对象！

不仅如此，我还知道 Visual Studio 不需要它。例如，当我写出对this library function 的调用时，它能够收集到参数对象需要名为id、source 和target 的属性，并在我为函数的参数 - 没有一行文档。大概是因为它们被使用这样一个简单的事实：

当然，如果这些属性不在对象上且类型不正确，该方法确实会抛出异常，但仍然如此。 编辑：我最近能够在我自己的代码中使用对象字面量参数来复制效果——我用一个定义明确的对象调用了一个函数，当我调用该函数时它给了我 Intellisense 建议再次在我的代码中的其他地方。但我仍然没有函数体内的类型信息或语义访问。

Visual Studio 显然理解配置对象的概念，并且正在做一些逻辑来提供建议的属性。那个算法是什么？以及如何在不破坏代码的情况下利用它？

Answer 1

您正在使用correct JSDoc syntax，但截至今天，Visual Studio 还没有为具有命名属性的参数对象构建正确的 IntelliSense。除了您提到的那个之外，目前没有其他方法可以解决这个问题，但是您可以在适当的位置描述 config 对象并避免编写您提到的死代码：

/**
 * @typedef  {object} TestConfig
 * @property {string} name
 * @property {number} gold
 *//**
 * @param    {TestConfig} config 
 */
function test(config) {

}

由于我们仅将此对象用于文档和自动完成目的，我们不需要实际编写代码。这并不比原始语法更冗长，而且还具有将配置对象记录在案的好处。

关于您的第二个问题，您可以看到 sigma.js 库的 IntelliSense 源自解析函数代码本身的主体，而不是 JSDoc cmets。这就是为什么当您将缩小的“sigma.min.js”构建添加到您的项目时仍然可以使用它，其中 cmets 已被剥离。

您可以测试类似于library function 中的这种添加参数验证（尽管以任何其他方式访问config.name 或config.gold 也会产生相同的结果）：

function do_it(config) {
    if (Object(config) !== config || arguments.length !== 1) throw 'do_it: wrong arguments.';
    if (typeof config.name !== 'string') throw 'config must have a name string field.';
    if (typeof config.gold !== 'number') throw 'config must have a gold number field.';
    ...
}

结果：

以类似的方式，一旦您提供了足够的信息，就会推断出正确的类型：