javascript - 在 VS Intellisense 的 JSDoc 类型定义中记录数组

Question

在我的 VS2015 JavaScript 应用程序中，我有一个从 REST API 获取的 JSON 对象，我使用 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 上下文时，我会看到“黄色三 Angular 形”菜单:

/**
 * @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 的其他推荐方法，使​​用 {Array.<JSON_Response>} , 通知 VS response是一个数组，但不为其下的任何内容提供 Intellisense。 Microsoft 自己的 XML 注释确实提供了此功能，但仅限于函数参数 - 我无法进入对象内部，我也不想这样做，因为每次调用函数时我都必须添加此文档。

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

如果我必须编写代码，我想尽量减少副作用/能够将其排除在发布之外。

Answer 1

好吧，所以这次我真的读到了你的问题(抱歉，我之前正忙着做某事)。

问题

Visual Studio 不会识别您用来定义数组中元素类型的 JSDoc 语法——至少在智能感知方面不会。

解决方案

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
}

---

记录 IntelliSense 的嵌套参数属性

关于您的评论和您对问题所做的编辑，您可以使用 param XML 评论的 value 属性指定参数的嵌套属性类型。 “值(value)”一词有点误导，因为根据 MSDN documentation ，它实际上并不用于指定一个值，而是一个值类型。见下文:

/**
 * @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
}

---

关于Companynerd225的替代方案

我不完全确定将 JSON 对象分类为类而不是类型是这里最准确的方法。此外，虽然我可能不知道它的正确术语，但我很确定返回 {id:0} 的函数与返回 this 的函数不同。见下文:

更不用说，您最终会用类型填充您的 JSDoc“类”部分。默认情况下，它在您的导航中看起来像这样:

---