Javascript 在JSDoc typedefs中为VS Intellisense记录数组

在我的VS2015 JavaScript应用程序中，我有一个JSON对象，它是从REST API获得的，我使用JSDoc

@typedef

注释记录了该对象：

/**
 * @typedef {Object} JSON_Response
 * @property {Number} id
 * @property {String} name
 * @property {JSON_Response_Tag} tag
 */

/**
 * @typedef {Object} JSON_Response_Tag
 * @property {Number} id
 * @property {String} color
 */

当我在使用这些JSON对象的方法的JSDoc注释中引用这种类型时，我可以很好地获得Intellisense文档：

/**
 * @param {JSON_Response} response
 */
function process_response(response) {
  // process response here...
}

但是，我无法将其用于数组-当我尝试为数组编制索引时，会出现“黄色三角形”菜单，当VS无法为您获取Intellisense上下文时会出现该菜单：

/**
 * @typedef {Object} JSON_Response
 * @property {Number} id
 * @property {String} name
 * @property {JSON_Response_Tag[]} tags
 */

/**
 * @param {JSON_Response} response
 */
function process_response(response) {
  response.tags[0]. // no intellisense here
}

JSDoc推荐的另一种方法是使用，它通知VS

response

是一个数组，但不提供该数组下任何内容的Intellisense。Microsoft自己的XML注释确实提供了此功能，但仅针对函数参数—我无法访问对象内部，我也不想这样做，因为每次调用函数时我都必须添加此文档

有没有办法在JavaScript的VS Intellisense中记录数组及其底层类型

---

如果我必须编写代码，我想最小化副作用/能够将它从发布中分解出来。

< P>好的，所以这次我实际阅读了你的问题（对不起，我是在某个早期的中间）。 问题 VisualStudio不会识别用于定义数组中元素类型的JSDoc语法，至少在涉及intellisense的地方不会

解决方案 XML是这里的解决方案。您可能知道这一点，但可以将JSDoc标记与XML注释结合使用，以规避其各自的限制。我不确定您在前面运行测试时使用了哪些标记和属性，但下面是代码的正确实现：

/**
 * @typedef {Object} JSON_Response
 * @property {Number} id
 * @property {String} name
 * @property {JSON_Response_Tag} tag
 */

/**
 * @typedef {Object} JSON_Response_Tag
 * @property {Number} id
 * @property {String} color
 */

/**
 * @param {JSON_Response[]} response
 */
function process_response(response) {
    /// <param name='response' type='Array' elementType='JSON_Response'></param>

   response[0]. // intellisense works here
}

---

关于公司的替代解决方案 我不完全确定将JSON对象分类为类而不是类型是这里最准确的方法。此外，尽管我可能不知道它的正确术语，但我非常确定返回

{id:0}

的函数与返回

this

的函数不同。见下文：

/**
 * @typedef {Object} JSON_Response
 * @property {Number} id
 * @property {String} name
 * @property {JSON_Response_Tag[]} tag
 */

/**
 * @typedef {Object} JSON_Response_Tag
 * @property {Number} id
 * @property {String} color
 */

/// <summary name='JSON_Response_Tag' type='Object'>my test summary</summary>
/// <field name='id' type='Number'>testid</field>
/// <field name='color' type='String'>testcolor</field>

/**
 * @param {JSON_Response} response
 */
function process_response(response) {
    /// <param name='response' type='JSON_Response' value='{id:0,name:"",tag:[{id:0,color:""}]}'></param>

    response.tag[0]. // intellisense works here
}

更不用说，最终会用类型填充JSDoc的“类”部分。默认情况下，它在导航中的外观如下所示：

---

---

这似乎有悖常理，但获取JSON类型文档的最佳方法是实际编写生成类型的构造函数，而不是为XML注释的局限性和Intellisense解析JSDoc的能力有限而烦恼，然后引用它，以便仅出于文档目的对其进行分析

换句话说，JavaScript中的构造函数如下所示：

/**
 * @constructor {Object} JSON_Response
 * @property {Number} id
 * @property {String} name
 * @property {JSON_Response_Tag[]} tags
 */
function JSON_Response(){
  return {
    id: 0,
    name: "",
    tags: [new JSON_Reponse_Tag()]
  }
}

/**
 * @constructor {Object} JSON_Response_Tag
 * @property {Number} id
 * @property {String} color
 */
function JSON_Response_Tag(){
  return {
    id: 0,
    color: "#000000"
  }
}

您不一定需要定义的所有单个对象类型：您可以使用任何您想要的。您甚至可以复制并粘贴JSON输出的示例。如果要在其他变量中存储内部对象，只需划分类

然后，您可以将所有这些JSON构造函数放在一个单独的文件中，并放置一个XML引用指令，而不是在页面中实际包含JavaScript文件

/// <reference path="~/path/to/schema_file.js" />

//

---

在使用JavaScript文件的顶部，Visual Studio运行代码的唯一目的是提供文档。

对不起，这并不能回答我的问题。这些是我在代码中没有定义的故意伪造的类型。问题是我需要能够访问这些类型的数组，而不是单个实例。@Compynerd255请参阅我的修订答案。那里的代码既可以用于文档生成，也可以用于准确的intellisense。好的，这更有意义。不过，我意识到我需要编辑我的问题：问题是数组在JSON对象中，XML注释无法触及它。谢谢。这确实可行，但需要在数据的每个消费者内部重复知识。事实上，我找到了一个更好的解决方案（发布为答案）。您可能已经解决了这些问题，但我在这里看到了一些问题。我假设您会从JSDoc命令中省略scheme文件？否则，在JSDoc文档中，您将得到一堆类而不是类型。我现在看到的所有其他问题都源于此；e、 例如，在为intellisense维护构造函数的同时，如何正确维护文档的typedefs而不复制代码？这些将取代typedefs。由于JSON总是返回一个对象作为根，所以这些类型总是类。我还在学习，但是你的那些函数不是返回对象文本，而不是类吗？它们就是TypeDef的用途，不是吗？您必须返回“this”才能使它们成为类。它们没有实例，因为它们都返回同一个新创建的对象。假设我说它们不是类是正确的，那么您的“类”部分不应该被什么类型所污染吗？当您使用

new

调用函数返回对象时，它会覆盖“使用函数的原型创建新对象并将其绑定到

此

”行为，只需将该对象提供给调用者（并允许

此

超出范围）。在任何意义上，它仍然是一个构造函数，JSDoc和VS Intellisense以这种方式记录它，将有限的信息外推到完整类型。这些是真正的对象类，就像允许构造函数返回

this

生成一个类一样。我可能不知道用什么术语来充分描述返回

this

的函数和返回对象的函数之间的区别，但我很确定它们是不同的。我在上面的回答中添加了一些顾虑。