在VS Intellisense的JSDoc typedef中记录数组

Question

在我的VS2015 JavaScript应用程序中,我有一个JSON对象,我从使用JSDoc @typedef注释记录的REST API获得:

/**
 * @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的另一个推荐方法,使​​用{Array.<JSON_Response>},通知VS response是一个数组,但不提供Intellisense的任何东西.微软自己的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
}

为智能感知记录嵌套参数属性

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

/**
 * @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“类”部分。默认情况下，它在您的导航中看起来像这样：