CODEWITHSUNDEEP
javascripteslintjsdoc
Hector Ricardo
Hector Ricardo

Reputation: 559

How to document parameter of class type extending another class with JSDoc?

Suppose I have this javascript code that defines a class. One of its static methods returns a class with which to instantiate children.

class ParentClass {
  /**
   * Creates an instance of parent class
   *
   * @param {string} type - the type of the instance.
   */
  constructor(type) {
    this.type = type;
  }

  /**
   * Creates a child class.
   *
   * @param {string} type - the type.
   *
   * @returns {class<ParentClass> ?? ----- WHAT GOES HERE?? -----} the resulting class.
   */
  static createChildClass(type) {
    return class extends ParentClass {
      constructor() {
        super(type);
      }
    };
  }

}

I am using the eslint plugin eslint-plugin-jsdoc to check the JSDoc comments in the code.

My question is: what is the correct way to document a type (either in a @param or @returns) which is a class that extends from another class? In other words, how do I document the @returns marked in the code above?

Upvotes: 1

Views: 4339

Answers (2)

danfuzz
danfuzz

Reputation: 4353

If you use the Google Closure type syntax (which JSDoc supports), you can document a class as the type of the constructor function (which it really is under the covers).

@param {function(new:SomeClass, arg1, arg2)}

See https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System for more detail.

Upvotes: 1

Brett Zamir
Brett Zamir

Reputation: 14345

jsdoc does not document any special syntax for representing a type that extends a class.

On the one hand, you might get by just using ParentClass as the type (implying that this interface is what is returned)--considering that jsdoc is really a documentation tool rather than a strict type checker (and JavaScript methods more often than not just expect a particular (duck-typable) interface rather than imposing instanceof checks or such).

However, you could give a more precise definition of your return type like such, using the @augments tag (also available in jsdoc as @extends, and required as such in Closure):

class ParentClass {

  // ...

  /**
   * Creates a child class.
   *
   * @param {string} type - the type.
   *
   * @returns {ChildClass} the resulting class.
   */
  static createChildClass(type) {
    /**
     * @class ChildClass
     * @augments ParentClass
     */
    return class extends ParentClass {
      constructor() {
        super(type);
      }
    };
  }
}

(IIRC, though jsdoc doesn't document use of brackets with @extends as Closure apparently requires, I believe it may work with the brackets.)

Note that this is still a bit of a hack, however, as we are not documenting that a particular instance is returned, but we want to document that a whole class is returned. See https://github.com/jsdoc/jsdoc/issues/1349 for an unimplemented issue. (TypeScript allows typeof with types, e.g., @returns {typeof ChildClass}.)

Upvotes: 2

Related Questions