documentation - Documenting the return of a javascript constructor with jsdoc - Stack Overflow

admin管理员组

文章数量:1287485

I have a javascript function that returns a constructor (see code sample below). How would I document this with the @returns tag of jsdoc. It doesnt seem correct to do @returns {MyConstructor} because that implies I am returning an instance of "MyConstructor" rather than the constructor itself, right?

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

I have a javascript function that returns a constructor (see code sample below). How would I document this with the @returns tag of jsdoc. It doesnt seem correct to do @returns {MyConstructor} because that implies I am returning an instance of "MyConstructor" rather than the constructor itself, right?

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
• documentation
• jscript
• jsdoc
• jsdoc3

Share Improve this question Follow edited Jan 8, 2014 at 17:34 putrius asked Jan 8, 2014 at 17:19 putriusputrius 70277 silver badges1717 bronze badges 8

• Why would you want to return a constructor. Seems like you're doing pointless things just like the use of self at the top... – marekful Commented Jan 8, 2014 at 17:24
• 1 I have a reason that is not apparent in the example above that is a bit plicated to explain. But it isn't relevant or necessary to be able to answer the question. – putrius Commented Jan 8, 2014 at 17:25
• So what about @returns MyConstructor? – marekful Commented Jan 8, 2014 at 17:26
• 2 From the question: " It doesnt seem correct to do @returns {MyConstructor} because that implies I am returning an instance of "MyConstructor" rather than the constructor itself, right?" – putrius Commented Jan 8, 2014 at 17:27
• 1 Yeah, I could say that in the description, but I was more looking for if there was a proper way to indicate that as the data type. – putrius Commented Jan 8, 2014 at 17:30

 |  Show 3 more ments

4 Answers 4

Sorted by: Reset to default 3

I do not think there is a way to use the brackets after @returns to document returning a specific instance. What goes in the brackets is interpreted as a type, always. This being said, there's a way to document that a specific instance of a type is being returned, by documenting the instance and using a link to the instance. I've shortened the code in the question to the essentials necessary to illustrate:

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

}

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

It can also be done with other things than classes:

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

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

As far as I know, this is as good as it gets with jsdoc 3.

Maybe little bit late, but I have problem to find proper answer for your question event today.

When I try generate JSDoc automatically on WebStorm, this is what I get:

class Test {}

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

Return type definition is still strange, but constructor annotation may fulfill the purpose.

You can check the types returned by your functions using:

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

In the documentation it says:

/**
 * 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/tags-returns.html

So in you example it would be:

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

Or if you are creating an instance of an Item:

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

you can use:

@returns {new () => MyConstructor}

This turns the return object into an anonymous constructor which creates the MyConstructor type.

you can bine this with & pretty flexibly to shape how the constructor looks (if you have static methods you want access to) as well as what the constructor creates (if you have partials that you're putting together in a factory)

本文标签： documentationDocumenting the return of a javascript constructor with jsdocStack Overflow