在VS Intellisense的JSDoc typedef中记录数组 [英] Documenting arrays in JSDoc typedefs for 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}回复
 * / 
函数process_response（响应）{
 //此处处理响应... 
} 
  

然而，我根本无法使用数组 - 当我尝试索引数组时，我得到了黄色三角形当VS无法获得Intell时发生的菜单isense context for you：

  / ** 
 * @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]。 //这里没有intellisense 
} 
  

JSDoc的其他推荐方法，使​​用

更不用说，你最终会用类型填充你的JSDoc类部分。默认情况下，它会在您的导航中显示如下：

---

In my VS2015 JavaScript app, I have a JSON object that I get from a REST API that I have documented using JSDoc @typedef comments:

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

When I reference this type in JSDoc comments on the methods that consume these JSON objects, I can get Intellisense documentation just fine:

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

However, I simply cannot get this to work with arrays - when I attempt to index the array, I get the "yellow triangles" menu that happens when VS can't get Intellisense context for you:

/**
 * @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's other recommended method, using {Array.<JSON_Response>}, informs VS that response is an Array but does not give Intellisense for anything under that. Microsoft's own XML comments do provide this capability, but only for function parameters - I can't reach inside the objects, nor would I like to do so because I'd have to add this documentation every time the function is called.

Is there any way to document arrays with their underlying types in JavaScript's VS Intellisense?

If I have to write code, I want to minimize the side effects / be able to factor it out of the release.

解决方案

Okay, so I actually read your question this time (sorry, I was in the middle of something earlier).

Issue

Visual Studio will not recognize the JSDoc syntax you are using to define the type of element within your array—at least not where intellisense is concerned.

Solution

XML is the solution here. You may be aware of this, but you can use JSDoc tags in conjunction with XML comments to circumvent their individual limitations. I'm not sure what tags and attributes you were using when you ran your tests earlier, but here is the correct implementation of your code:

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

---

DOCUMENTING NESTED PARAMETER PROPERTIES FOR INTELLISENSE

Regarding your comment and the edits you made to your question, you can specify nested property types of parameters using the value attribute of the param XML comment. The term "value" is a little misleading, because according to the MSDN documentation, it isn't used to actually specify a value but rather a value type. See below:

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

---

Regarding Companynerd225's alternate solution

I'm not entirely sure that categorizing JSON objects as classes instead of types is the most accurate method here. Also, although I may not know the proper terms for it, I'm pretty sure a function returning {id:0} is not the same as a function returning this. See below:

Not to mention, you would end up filling your JSDoc "Classes" section with types. By default, it would look like this in your navigation:

---

这篇关于在VS Intellisense的JSDoc typedef中记录数组的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！