JSDoc : add support for @method (and @property)

[qraynaud]

Search Terms

• JSDoc
• @method
• @property
• support

Suggestion

It would be great to add support for @method and @property (and maybe @memberof) now that annotations are on their way.

I found bug #15715 that only talks about @property support but I think this makes more sense to see those in a same light because they should have a very common implementation and moreover they meet the same goals as a whole. At least I think and I explain my reasoning about this below!

Use Cases

I have functions that do add methods and/or getters on a class right now, waiting for annotations to get their way in JS/TS. But let's say this: when annotations are here, those 2 flags support will be needed anyway (or at least I think so: I don't see how to make IntelliSense work without those)!

/**
* Some class
 * @class
 */
class Test {
  /* whatever */
}

// this adds a #foo() method on the class prototype as well as a #bar getter(/setter)
someMethodAddingABehavior(Test, ...params);

And tomorrow with annotations:

/**
* Some class
 * @class
 */
@someAnnotationAddingABehavior(...params)
class Test {
  /* whatever */
}

Examples

I'd like to be able to document those doing something like:

/**
 * What foo is doing is great!
 * @method foo
 * @param {string} testParam some testing parameter
 * @returns {string} some random string
 * @memberof Test.prototype
 */
/**
 * Bar is awesome too!
 * @property {number} bar
 * @memberof Test.prototype
 */
someMethodAddingABehavior(Test, ...params);

Or at least to be able to document them in the class itself:

/**
* Some class
 * @class
 */
class Test {
  /* whatever */

  /**
   * What foo is doing is great!
   * @method foo
   * @param {string} testParam some testing parameter
   * @returns {string} some random string
   */
  /**
   * Bar is awesome too!
   * @property {number} bar
   */
}

With support of these, I would expect vscode to suggest to me the foo method and the bar property when completing properties of a value of type Test.

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

[matt-tingen]

I'll second this. Our use case is a large number of classes of the following form:

import { extendObservable } from 'mobx';

class Foo {
  constructor() {
    extendObservable(this, {
      bar: 123,
      // ...
    });
  }
}

extendObservable behaves very similarly to Object.assign. However, we cannot use the following workaround because it is not forwards-compatible with extendObservable (we are on v3 and >= v4 does not override existing properties):

class Foo {
  /** @type {number} */
  bar;

  constructor () { /* ... */ }
}

[thw0rted]

Is there a current workaround for this? I'm trying to build typings (using tsc --allowJs) from a JS library that adds getter/setter properties outside the constructor function.

function Foo() { ... }

Object.defineProperties(Foo.prototype, {
  /**
     * @memberof Foo
     * @type {number}
     */
  bar: { get: function() {...} },
  /**
     * @memberof Foo
     * @type {string}
     */
  baz: { get: function() {...} }, 
});

I'm not at liberty to convert this to a more straightforward pattern (like, say, an ES6 class) so I'm stuck trying to describe the way it works now such that the generated typings include the added properties.

[thw0rted]

Oof, looks like we've been waiting a while for this: #7237.

[Jet132]

This can be solved using interfaces and/or definite assignment assertions which also work for class properties (see this section).

[alex-polosky]

Oh cool, this is why JSDoc in Javascript isn't working. That sucks. Also means that the workaround won't work.