How to document non class-based instantiation (using Object.create)?

[drjayvee]

Consider this pattern:

/*jshint esnext:true*/

const Proto = {
    method () {}
};

function create () {
    return Object.create(Proto);
}

Proto is not a @class, since objects cannot be instantiated using new (it's not even a function at all). Instead we use a factory that creates objects that have Proto as their prototype. How can we document the return type of that factory?

I've experimented with @type, @typedef, @lends, but nothing yields sensible documentation. Not even lying by using @class works:

/*jshint esnext:true*/

/**
 * @class
 */
const Proto = /** @lends Proto.prototype */{
    /** A method */
    method () {}
};

/**
 * @return {Proto}
 */
function create () {
    return Object.create(Proto);
}

The resulting documentation lists Proto as a class (which it isn't, but we told jsdoc so, so that's okay), but lists method as static, which is wrong. None of the tags for Proto seem to have any effect - removing them produces the same documentation.

JSDoc is quite flexible when it comes to @typedef, but I can't get it to parse Proto as a non-class type.

[drjayvee]

This actually works ok:

/*jshint esnext:true*/
function createFactory (proto) {
    return () => {
        return Object.create(proto);
    };
}

/**
 * @function
 * @return {Proto}
 */
const create = createFactory(
    /** @lends Proto.prototype */
    {
        /** A method */
        method () {}
    }
);

Proto is still considered a class, but at least the methods are not static.

At the very least, I think it would be a good idea to write some documentation for annotating this kind of pattern. I don't understand why this works and the code in the opening post (which first constructs the object literal) does not.

[hegemonic]

Duplicate of jsdoc/jsdoc#1244.