VS2010 : javascript intellisense : specifying properties for 'options' objects passed to methods

Question

Since javascript intellisense actually seems to work in VS2010, I thought I might add some to those scripts I include in almost everything.

The trouble is, on some complex functions, I use option objects instead of passing umpteen different parameters, like so:

function myFunc(options){
    var myVar1 = options.myVar1,
        myVar2 = options.myVar2,
        myVar3 = options.myVar3;
    ...
}

the trouble I am running into is, there doesn't seem to be a way to specify what properties options needs to have. I've tried this:

function myFunc(options){
    ///<summary>my func does stuff...</summary>
    ///<param name="options">
    ///myVar1 : the first var
    ///myVar2 : the second var
    ///myVar3 : the third var
    ///</param>

    var myVar1 = options.myVar1,
        myVar2 = options.myVar2,
        myVar3 = options.myVar3;
    ...
}

but the line breaks are removed and all the property comments run together, making them stupidly hard to read.

I've tried the <para> tags, but to no avail.

If anyone has any ideas on how I might achieve this, please let me know.

-Brandon

Answer 1

The vsdoc file for jQuery uses that approach. You just have to try and format it so it's somewhat readable even when it's all on one line. For example, here's an excerpt from the jQuery 1.4.1 vsdoc file:

jQuery.fn[ "blur" ] = function( fn ) {
/// <summary>
///     1: blur() - Triggers the blur event of each matched element.
///     2: blur(fn) - Binds a function to the blur event of each matched element.
/// </summary>
/// <param name="fn" type="Function">The function to execute.</param>
/// <returns type="jQuery" />

return fn ? this.bind( "blur", fn ) : this.trigger( "blur" );

};

The resulting tooltips do put it all on one line, but it's still fairly readable, thanks to the structure of each of the items (especially because there is a '.' at the end of each one).