Visual studio web essentials JSDoc intellisense on methods assigned in constructor not working?

Question

I'm a little new to jsdoc comments (attempting to convert some vsdoc comments to jsdoc so I can make use of doc generators that support jsdoc), so stop me if I'm doing something obviously incorrect, but I noticed that if you assign methods on a constructor's prototype, intellisense works for that member:

/** 
 * @constructor 
 * @this {Foo} 
 */ 
function Foo() {}

/** 
 * A bar of Foo for you.
 * @param {string} baz A foo bar baz. 
 * @return {string} You get back what you give. 
 */ 
Foo.prototype.bar = function(baz) { return baz; }

But, if you assign bar in the constructor, the intellisense on the bar method breaks - it just shows the entire comment, jsdoc tags and all, as a single block. It doesn't display argument types or flow the return value through:

/** 
 * @constructor 
 * @this {Foo} 
 * @param {string} baz A foo bar baz. 
 */ 
function Foo(baz) { 
  /** 
   * A bar of Foo and something else too.
   * @param {string} barzipan A little something extra. 
   * @return {string} You get back what you gave, and then some. 
   */ 
  this.bar = function(barzipan) { return baz + barzipan; }; 
}

The vsdoc intellisense parser is able to handle either methods on the prototype or methods assigned to this, but the jsdoc parser appears to be confused by methods assigned to this in a constructor.

score 2 · Accepted Answer · answered Oct 05 '16 at 12:11

To handle this, you need to add a few more bits of syntactic sugar to the jsdoc values. This is because the parser doesn't know to translate 'this.bar()' to 'Foo.bar()'. To resolve it, add something like the following:

/** 
 * @constructor 
 * @this {Foo} 
 * @param {string} baz A foo bar baz. 
 */ 
function Foo(baz) { 
  /** 
   * A bar of Foo and something else too.
   * @param {string} barzipan A little something extra. 
   * @return {string} You get back what you gave, and then some. 
   * @function bar
   * @memberof {@link Foo}
   */ 
  this.bar = function(barzipan) { return baz + barzipan; }; 
}

See JSDoc @memberof and JSDOC @function. This can also help you when you want to create a private function (To document privates, use the -p command when running JSDOC).

function Foo(baz) {
    /**
     * Returns what Bob did...
     * @param {string} doStuff Stuff to pass in.
     * @function bob
     * @memberof Foo
     * @private
     */
    var bob = function(doStuff) {
         return "Bob did " + doStuff;
    }
}

Visual studio web essentials JSDoc intellisense on methods assigned in constructor not working?

1 Answers1