PHPDoc для свободного интерфейса в подклассе?

Есть ли какие-либо причины, чтобы моя IDE (фактически PHPStorm) понимала это:

$student->setName('Marco'); 

setName() экземпляр Student , не переопределяя setName() в подклассе (только для добавления комментариев PHPDoc)?

 class Person { private $name; /** * @param string $name * @return Person */ public function setName($name) { $this->name = $name; return $this; } } class Student extends Person { } 

Вы можете вернуть $ this вместо человека в своем докблоке

вы должны перезаписать свой тег метода как комментарий, как это

 /** * @method Student setName($name) */ class Student extends Person { } 

По моему опыту, я нашел полезным использовать комбинированный подход. Моя IDE (IntelliJ IDEA с плагином PHP) жаловалась, что мои быстрые методы возвращали $this когда это значение позднее использовалось в качестве параметра для вызова другого метода. Изменив комментарий PHPDoc на это:

 /** * @param string $name * @return $this|Person */ 

IDE была более счастливой, и PHPDoc более информативен для пользователя.

Кстати, говоря, что метод возвращает $this в PHPDoc, это очень хороший признак того, что этот метод реализует свободный интерфейс. Говорить, что он возвращает Person , хотя и технически точен, необязательно означает беглость. Например, метод, который создает новый объект Person и возвращает его, также может использовать эту же аннотацию, но он не будет бегло.