如何在 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 呈现为三个独立的顶级参数。

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

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

不仅如此，我也知道Visual Studio不需要。例如，当我写出对 this library function 的调用时，它能够收集到参数对象需要称为 id、source 和 target 的属性，并建议这些当我为函数的参数创建对象文字时的名称 - 并且 没有一行文档 。据推测，它来自一个简单的事实，即它们 used:

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

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 注释。这就是为什么当您将缩小的 "sigma.min.js" 构建添加到您的项目时仍然可以使用它，其中注释已被删除。

您可以测试此添加参数验证，类似于 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.';
    ...
}

结果：

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

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

How to document JavaScript configuration objects in Visual Studio Intellisense

javascript

documentation

javascript-intellisense

jsdoc

visual-studio-2015