Документирование возврата конструктора javascript с помощью jsdoc

У меня есть функция javascript, которая возвращает конструктор (см. пример кода ниже). Как бы я задокументировал это с помощью тега @returns jsdoc. Кажется неправильным делать @returns {MyConstructor}, потому что это подразумевает, что я возвращаю экземпляр «MyConstructor», а не сам конструктор, верно?

function MyConstructor() {
    var self = this;

    self.myFunction = function() {
        return true;
    };

    self.getMyFunctionResult = function() {
        return self.myFunction();
    };
}

/**
 * @returns {?} A constructor that will be instantiated
 */
function getConstructor() {
    return MyConstructor;
}

var constructor = getConstructor();
var instance = new constructor();

javascript jsdoc documentation jscript jsdoc3
person computrius    schedule 08.01.2014    source источник
comment
Почему вы хотите вернуть конструктор. Похоже, вы делаете бессмысленные вещи, такие как использование self вверху...   -  person marekful    schedule 08.01.2014
comment
У меня есть причина, не очевидная в приведенном выше примере, которую немного сложно объяснить. Но это не имеет значения или необходимо, чтобы быть в состоянии ответить на вопрос.   -  person computrius    schedule 08.01.2014
comment
Так что насчет @returns MyConstructor?   -  person marekful    schedule 08.01.2014
comment
Из вопроса: кажется неправильным делать @returns {MyConstructor}, потому что это подразумевает, что я возвращаю экземпляр MyConstructor, а не сам конструктор, верно?   -  person computrius    schedule 08.01.2014
comment
Да, я мог бы сказать это в описании, но я больше искал, есть ли правильный способ указать это как тип данных.   -  person computrius    schedule 08.01.2014
comment
Пс. var self в этом примере на самом деле не нужен. Это просто для полноты. Это становится необходимым, поскольку определение this изменяется внутри функций-членов (например, если мне нужно вызвать второй общедоступный метод изнутри другого общедоступного метода).   -  person computrius    schedule 08.01.2014
comment
Для тех, кто считает это бесполезным, есть пример Sequelize models. Метод init можно переопределить, он всегда будет возвращать сам класс. Другой пример — беглые статические классы.   -  person Maxwell s.c    schedule 31.12.2019

Ответы (3)


arrow_upward
2
arrow_downward

Вы можете проверить типы, возвращаемые вашими функциями, используя:

console.log(typeof constructor, typeof instance); // function object

В документации сказано:

/**
 * Returns the sum of a and b
 * @param {Number} a
 * @param {Number} b
 * @returns {Number} Sum of a and b
 */
function sum(a, b) {
    return a + b;
}

http://usejsdoc.org/tags-returns.html

Итак, в вашем примере это будет:

/**
 * Returns the MyConstructor class
 * @returns {Function} MyConstructor class
 */
function getConstructor() {
    return MyConstructor;
}

Или, если вы создаете экземпляр элемента:

/**
 * Returns an instance of the MyConstructor class
 * @returns {Object} MyConstructor instance
 */
function getInstance() {
    return new MyConstructor();
}
person Kim T    schedule 08.01.2014
comment
Так что, если я хочу уточнить функцию? Просто функция сама по себе не очень полезная документация; это мне ничего не говорит. Будет ли допустимо что-то вроде @returns {Function‹MyConstructor›} blaa? - person computrius; 08.01.2014
comment
Если вы определили функцию как класс: usejsdoc.org/tags-classdesc.html, вы можете объявить тип как класс: usejsdoc.org/tags-type.html - person Kim T; 08.01.2014
comment
Это говорит только о том, что return является функцией. Не говорит, какой класс он вернул. - person Maxwell s.c; 31.12.2019

arrow_upward
3
arrow_downward

Я не думаю, что есть способ использовать скобки после @returns для документирования возврата конкретного экземпляра. То, что заключено в скобки, всегда интерпретируется как тип. При этом есть способ задокументировать, что конкретный экземпляр типа возвращается, путем документирования экземпляра и использования ссылки на экземпляр. Я сократил код в вопросе до необходимого для иллюстрации:

/**
 * @class
 */
function MyConstructor() {

}

/**
 * @returns {Function} A constructor that will be instantiated. Always
 * returns {@link MyConstructor}.
 */
function getConstructor() {
    return MyConstructor;
}

Это также можно сделать с другими вещами, кроме классов:

/**
 * @public
 */
var foo = 1;

/**
 * @returns {number} {@link foo}.
 */
function getFoo(){
    return foo;
}

Насколько я знаю, это так же хорошо, как и в jsdoc 3.

person Louis    schedule 09.01.2014

arrow_upward
3
arrow_downward

Может быть, немного поздно, но сегодня у меня проблема с поиском правильного ответа на ваш вопрос.

Когда я пытаюсь автоматически сгенерировать JSDoc в WebStorm, я получаю следующее:

class Test {}

/**
 *
 * @return {Test}
 * @constructor
 */
function getTestConstructor() {
    return Test;
}

Определение типа возвращаемого значения все еще выглядит странно, но аннотация конструктора может выполнять эту задачу.

person TonyB    schedule 08.04.2019
comment
Intellissense не распознает его :( - person Maxwell s.c; 31.12.2019