- summary - used for functions, including constructors
- param - used for function parameters
- field - used for class fields
- value - used for properties on the getter function (the setter remains empty)
- returns - used for specifying the return values
Heres a code snippet example
Details, Details, Details
I'll now go through how this works in practice and highlight some of the information I had to dig and experiment for.
In order for Intellisense to pick up the fields I also had to add a registerClass line underneath - otherwise all the field tags were ignored.
In terms of comparing vs-doc with JSDoc, this is for me the biggest failing of vs-doc. Once an XML comment describing a field is separated from where that field is being used or accessed, then you increase the risk that a developer will change or remove that field without changing the comment. You also no longer have reminders where all the field initialisers are, that XML tags need to be updated.
When you don't add vs-doc comments, you don't get Intellisense on fields when using them within the class. It does pick up, that if a field has been modified earlier in the function you are editing, that it is available now, but that doesn't stop a earlier mistake being duplicated and accessing a mis-spelt field. When you use the created class, the Intellisense on the instance picks up a mixture of all fields defined in field tags and set in the constructor that do not begin with underscore (Microsoft's convention for private fields - even though they are not enforced to be private).
References worked well, but using name="" didn't work for files in the same project, even if the file was in the same folder, however you can work around it by using path="" instead, which also allowed me to pull in files from other projects. They do chain though, so once I add some base files referenced (like the jQuery vs-doc) in one file, referencing that gave me full jQuery Intellisense.
Dom Elements don't have a type. Instead you leave off the type attribute and have a domElement="true" instead. I found it worked for pre-written functions returning dom elements and me then using them, but if a param was a dom element then Intellisense failed to give me any help in my function - though the param tag also didn't always work with types.
AJAX enumerations (where registerEnumeration is used) cause every field tag and item set in the constructor to be marked as static and be available on the type (despite in fact only objects on the prototype being copied to the type). One tag used by the Microsoft Ajax team but not in mentioned anywhere else (and currently ignored by Intellisense) is static="true|false". Below is a code example showing how the Microsoft team annotate enumerations.
When you attempt to get the functions/fields on the variable value (at the point indicated by the star), you get Value1 and Value2 - Intellisense thinks that value is an instantiation of the MyEnumeration class rather than a number that will be present on the MyEnumeration prototype.
Here is a list of recognised value types - Number, Array, Function, Object, Boolean. I haven't found a value type for an event (and there is no equivalent domEvent="true"), however there are the two Microsoft Ajax wrapper classes, Sys.Dom.DomEvent and Sys.EventArgs.
To compare JSDoc to vs-doc, I much prefer the brevity of JSDoc in being able to say something's type is "number|null" instead of having to set an attribute mayBeNull="true" or using question mark to denote a optional parameter instead of optional="true". With all the field XML you end up with a big unreadable chunk at the beginning of your constructor that is unmaintainable and provides little benefit. It is a shame Microsoft didn't make some effort to support JSDoc, even if it required adding some custom tags so that developers aren't stuck between having slightly better Intellisense and Microsoft code documentation (vs-doc) or having a better annotation system that is more widely used (JSDoc).
However, with some improvements to Intellisense and the ability to annotate a field anywhere in the constructor (or even class) then the advantages could start outweighing the maintainability.