PHPDoc: document parent class method that always yields itself or descendant class?

Viewed 1773

Consider this code:

class ParentClass {

    public static function generate($className = __CLASS__){
        if(!$className) return new self();
        else return new $className();
    }
}

class ChildClass extends ParentClass {

    /**
     * @param string $className
     * @return ChildClass
     */
    public static function generate($className = __CLASS__) {
        return parent::generate($className);
    }
}

var_dump($ChildClass::generate()); // object(ChildClass)[1]

ChildClass::generate() returns an instance of ChildClass wherever I use it because I never provide a $className argument. Problem is that my IDE gives me a warning about the parent::generate() call not matching the documented return type:

enter image description here

I would like to make this warning go away by adding documentation to the parent method. I could do:

@return ParentClass | ChildClass

Adding this to the parent method works but that's not practical because there are many dozen children classes, and there could be many more in the future. I have tried both of the following:

@return static
@return $className

but that hasn't made the warning go away. Is there a PHPDoc approved way to indicate that the calling child class will always be returned? Or -- more accurately -- that a class of type $className will be returned? If not, is there a way that works even with just my IDE? (PhpStorm 2017.2)

Update

@gogaz comment below got me to think: it would be enough if a PHPDoc @return could indicate something like self | descendants

2 Answers
Related