Documentando o retorno de um construtor javascript com jsdoc

Question

Eu tenho uma função javascript que retorna um construtor (veja o exemplo de código abaixo).Como eu documentaria isso com a tag @returns do jsdoc.Não parece correto fazer @returns {MyConstructor} porque isso implica que estou retornando uma instância de "MyConstructor" em vez do próprio construtor, certo?

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

Answer 1

Você pode verificar os tipos retornados pelas suas funções usando:

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

Na documentação diz:

/**
 * 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

Então no seu exemplo seria:

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

Ou se você estiver criando uma instância de um Item:

/**
 * Returns an instance of the MyConstructor class
 * @returns {Object} MyConstructor instance
 */
function getInstance() {
    return new MyConstructor();
}

Answer 2

Eu não acho que haja uma maneira de usar os colchetes depois @returns para documentar o retorno de um específico instância.O que está entre colchetes é interpretado como tipo, sempre.Dito isto, há uma maneira de documentar que uma instância específica de um tipo está sendo retornada, documentando a instância e usando um link para a instância.Reduzi o código da pergunta ao essencial necessário para ilustrar:

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

}

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

Também pode ser feito com outras coisas além das classes:

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

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

Pelo que eu sei, isso é o melhor possível com o jsdoc 3.

Answer 3

Talvez um pouco tarde, mas tenho problemas para encontrar a resposta adequada para sua pergunta hoje.

Quando tento gerar JSDoc automaticamente no WebStorm, é isso que recebo:

class Test {}

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

A definição do tipo de retorno ainda é estranha, mas a anotação do construtor pode cumprir o propósito.