Documenting a class returning another class

[OmgImAlexis]

Input code

/**
 * Canvas
 *
 * @class Canvas
 */
class Canvas {
    /**
     * Creates an instance of Canvas.
     * @returns {HTMLCanvasElement}
     * @memberof Canvas
     */
    constructor(width, height) {
        const canvas = document.createElement('canvas');
        canvas.width = width;
        canvas.height = height;

        return canvas;
    }
};

Expected behavior

This is the js output, so I know this works.

const canvas = new Canvas(600, 800);
console.log(canvas.width); // 600

Current behavior

This is what happens when using a jsdoc plugin and hover over the width.
I would have expected the width to show that it's a number.

const canvas = new Canvas(600, 800);
console.log(canvas.width); // `undefined`

[philiprollins]

Constructors should not have a return statement, the purpose of the constructor is to CONSTRUCT the object not some other object. You should switch that to either extending the HTMLCanvasElement class or a creation type function returning the element.

[OmgImAlexis]

If the language allows it then it should be supported by jsdoc.
Go and run the code in your browser, it's valid Javascript.

[philiprollins]

There's a lot of valid JavaScript that shouldn't be valid. Just because you can do something doesn't mean you should.

Bunch of hacks

[OmgImAlexis]

Oh just go away. I really don’t get why people feel the need to drive by and just drop comments for no good reason. This is valid JavaScript. I can use this in the language. I should be able to document it.

Just because you done like certain ways of writing code doesn’t mean others should be prevented from doing so.

[philiprollins]

No good reason? Besides explaining why it should not be implemented? Carry on being a child and disliking every comment I post lol.

Perhaps you should learn to read and comprehend. In the simplest of terms, hacks are not supported or used by any reputable sources. Fork the project to add support for hacks.

ECMAScript class specs

[gryphonmyers]

Taken from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/new:

When the code new Foo(...) is executed, the following things happen:

1. A new object is created, inheriting from Foo.prototype.

2. The constructor function Foo is called with the specified arguments, and with this bound to the newly created object. new Foo is equivalent to new Foo(), i.e. if no argument list is specified, Foo is called without arguments.

3. The object (not null, false, 3.1415 or other primitive types) returned by the constructor function becomes the result of the whole new expression. If the constructor function doesn't explicitly return an object, the object created in step 1 is used instead. (Normally constructors don't return a value, but they can choose to do so if they want to override the normal object creation process.)

It's not common, but there are legitimate cases where one might return a different value in a constructor. As an example, one might want to return a Proxy object wrapping the value of this, allowing for trapping the instantiated object.