Documenting arrays in JSDoc typedefs for VS Intellisense

Question

In my VS2015 JavaScript application, I have a JSON object that I get from the REST API, which I 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 refer to this type in JSDoc comments on methods that consume these JSON objects, I can get the Intellisense documentation just fine:

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

However, I just can't get this to work with arrays - when I try to index the array, I get a menu of yellow triangles, which happens when VS cannot get the 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 is another recommended method, using {Array.<JSON_Response>} , tells VS that response is an array, but does not give Intellisense for anything underneath. Microsoft's own XML comments provide this feature, but only for function parameters - I don't I can get inside objects, and I would not want to do this because I had to add this documentation every time a function is called.

Is there a way to document arrays with their base types in JavaScript VS Intellisense?

If I need to write code, I want to minimize side effects / be able to exclude it from the release.

Answer 1

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

Problem

Visual Studio does not recognize the JSDoc syntax that you use to determine the type of element in your array - at least not with regard to intellisense.

Decision

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 used when you ran your tests before, 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 } 

---

DOCUMENTATION OF MALFUNCTIONS OF PARAMETERS FOR INTELLIGENCE

As for your comment and the changes you made to your question, you can specify the properties of the attached properties using the value attribute of the param XML comment. The term "value" is a bit misleading, because according to the MSDN documentation , it is not used to actually indicate the value, but rather the type of value. 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 Alternative

I'm not quite sure that categorizing JSON objects as classes instead of types is the most accurate method here. Also, although I may not know the correct terms for this, I am sure that the function that returns {id:0} is not the same as the function that returns this . See below:

Not to mention that you will finish filling out the JSDoc Classes section with types. By default, this will look in your navigation:

---

Answer 2

It seems counterintuitive, but the best way to get documentation of your JSON types, rather than worry about XML comment restrictions and Intellisense's limited ability to parse JSDocs, is to write constructors that produce your types , then reference it so that it is parsed only for purposes documentation.

In other words, you have constructors in your JavaScript that look like this:

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

You do not necessarily need all the individual types of objects: you can use whatever you want. You can even copy and paste a sample of your JSON output. You only need to separate classes if you intend to store internal objects in other variables.

And then instead of actually including the JavaScript file on your page, you can put all these JSON constructors in a separate file and put the XML link directive

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

at the top of your downloadable JavaScript files - Visual Studio will run the code for the sole purpose of providing documentation.