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`

[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.

[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.

[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.

[GabrielRalph]

You could try this

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

        return canvas;
    }
};