Documenting the return of a javascript constructor with jsdoc

Question

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

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
– marekful, Commented Jan 8, 2014 at 17:24
I have a reason that is not apparent in the example above that is a bit complicated to explain. But it isn't relevant or necessary to be able to answer the question. — computrius
– computrius, Commented Jan 8, 2014 at 17:25
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?" — computrius
– computrius, Commented Jan 8, 2014 at 17:27
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. — computrius
– computrius, Commented Jan 8, 2014 at 17:30

Louis · Accepted Answer · 2014-01-09 13:34:51Z

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.

TonyB · Accepted Answer · 2019-04-08 12:39:33Z

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.

answered Apr 8, 2019 at 12:39

TonyB

4335 silver badges11 bronze badges

1 Comment

Maxwell s.c Over a year ago

Intellissense doesn't recognize it :(

Kim T · Accepted Answer · 2014-01-08 18:02:21Z

2

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.org/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();
}

answered Jan 8, 2014 at 18:02

Kim T

6,5782 gold badges63 silver badges85 bronze badges

3 Comments

computrius Over a year ago

So what if I wanted to be more specific about "Function"? Just "Function" alone isnt really useful documentation; it doesnt tell me anything. Would something like "@returns {Function<MyConstructor>} blaa" be valid?

Kim T Over a year ago

If you have defined the function as a class: usejsdoc.org/tags-classdesc.html then you can declare the type as a class: usejsdoc.org/tags-type.html

Maxwell s.c Over a year ago

This only tells that the return is an function. Doesn't tell what class its returned.

David Torrey · Accepted Answer · 2023-03-19 07:37:30Z

0

you can use:

@returns {new () => MyConstructor}

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

you can combine 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)

answered Mar 19, 2023 at 7:37

David Torrey

1,3623 gold badges21 silver badges45 bronze badges

Collectives™ on Stack Overflow

Documenting the return of a javascript constructor with jsdoc

4 Answers 4

Comments

1 Comment

3 Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

4 Answers 4

Comments

1 Comment

3 Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related