"Wrong returns value" warning ignores subclasses (@class and @extends support)

[cowwoc]

Given:

        /**
         * Create a new precondition.
         *
         * @param {Object} parameter the parameter value
         * @param {String} name the parameter name
         * @return {ObjectPreconditions} the precondition
         */
        Preconditions.requireThat = function(parameter, name)
        {
            ObjectPreconditions.instanceOf(name, "name", String);
            if (Utilities.instanceOf(parameter, String))
                return new StringPreconditions(parameter, name);
            if (Array.isArray(parameter))
                return new ArrayPreconditions(parameter, name);
            return new ObjectPreconditions(parameter, name);
        };

where ArrayPreconditions and StringPreconditions both subclass ObjectPreconditions as follows:

        /**
         * @class ObjectPreconditions
         */
    function ObjectPreconditions(parameter, name)
    {
          ...
        }

        /**
         * @class StringPreconditions
         * @extends ObjectPreconditions
         */
    function StringPreconditions(parameter, name)
    {
      ...
    }
    StringPreconditions.prototype = Object.create(ObjectPreconditions.prototype);
    StringPreconditions.prototype.constructor = ObjectPreconditions;

I am expecting to be able to return ObjectPreconditions without having to specify every possible subclass. From the end-user's point of view, the subclasses are an implementation detail.

[qfox]

Internal mechanics of jscs doesn't allow this for now. Probably only if all extendable and final classes are placed in one file.

On the flip side jscs is a code styling tool, so I'm looking at jscs-jsdoc as jsdoc styling plugin. I think if you want to check code more accurately you should use some analysis tool but not styling.

But we can think about it anyway. Just to clarify. @mdevils can we somehow collect this data from all files? Looks like post-check hook or finalize.