Как задокументировать параметр типа класса, расширяющий другой класс с помощью JSDo c? - PullRequest
Новая
       4

Как задокументировать параметр типа класса, расширяющий другой класс с помощью JSDo c?

0 голосов
/ 09 января 2020

Предположим, у меня есть javascript код, который определяет класс. Один из его методов stati c возвращает класс для создания экземпляров потомков. 

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);
      }
    };
  }

}

Я использую плагин eslint eslint-plugin-jsdoc для проверки комментариев JSDo c в коде.

Мой вопрос: как правильно документировать тип (либо в @param, либо @returns), который является классом, который происходит от другого класса? Другими словами, как мне документировать @returns, отмеченный в коде выше?

1 Ответ

0 голосов
/ 24 апреля 2020

jsdo c не документирует никакого специального синтаксиса для представления типа, расширяющего класс.

С одной стороны, вы можете получить, просто используя ParentClass в качестве type (подразумевая, что этот интерфейс является тем, что возвращается) - учитывая, что jsdo c действительно инструмент для документирования, а не для строгой проверки типов (и JavaScript методы чаще, чем просто ожидают определенного (типизируемого утилитой) интерфейса вместо наложения instanceof чеков или тому подобного).

Однако вы можете дать более точное определение типа возвращаемого значения, например, с помощью тега @augments (также доступного в jsdo c как @extends и требуется как таковое в 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);
      }
    };
  }
}

(IIR C, хотя jsdo c не документирует использование скобок с @extends, как, очевидно, требует Closure, я думаю, что он может работать с квадратными скобками.)

Обратите внимание, что это все же немного хак, поскольку мы не документируем, что конкретный экземпляр возвращается, но мы хотим документировать, что весь класс возвращается. См. https://github.com/jsdoc/jsdoc/issues/1349 для невыполненной проблемы. (TypeScript позволяет typeof с типами, например, @returns {typeof ChildClass}.)

...