title: PHPDoc: document parent class method that always yields itself or descendant class?
body: <p>Consider this code:</p>
  
  <pre><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]
  </code></pre>
  
  <p><code>ChildClass::generate()</code> returns an instance of <code>ChildClass</code> wherever I use it because I never provide a <code>$className</code> argument. Problem is that my IDE gives me a warning about the <code>parent::generate()</code> call not matching the documented return type:</p>
  
  <p><a href="https://i.stack.imgur.com/ryY9g.png" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/ryY9g.png" alt="enter image description here"></a></p>
  
  <p>I would like to make this warning go away by adding documentation to the parent method. I could do:</p>
  
  <pre><code>@return ParentClass | ChildClass
  </code></pre>
  
  <p>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:</p>
  
  <pre><code>@return static
  @return $className
  </code></pre>
  
  <p>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 <code>$className</code> will be returned? If not, is there a way that works even with just my IDE? (<code>PhpStorm 2017.2</code>)</p>
  
  <h3>Update</h3>
  
  <p>@gogaz comment below got me to think: it would be enough if a PHPDoc <code>@return</code> could indicate something like <code>self | descendants</code></p>