Каково соглашение для тега @return, если метод переопределяет и возвращает результат метода родителя?
Если у меня есть метод в каком-то классе, который возвращает логическое значение, например
class A {
/**
* This method doesn't do much
* @return boolean
**/
public function a() {
// Do something
// ...
return true;
}
}
И затем у меня есть другой метод, который переопределяет этот, а затем вызывает родителя и возвращает результат родителя:
class B extends A {
/**
* @Override
* This method just does some extra work, before handing
* it over to class A's method
* @return what?
**/
public function a() {
// Do some extra stuff
// ...
// Then hand it over to the parent
return parent::a();
}
}
Что было бы лучше (обычнее) перечислить как B::a()возвращаемое значение? Должен ли он сказать, что он возвращается booleanили что он возвращает «значение родителя» и обращается к родителю за документацией? Или что-то другое?
С точки зрения написания, второй вариант представляется более разумным, поскольку, если изменяется возвращаемое значение родителя, это не повлечет за собой изменений в других частях документации. С точки зрения чтения, первый вариант кажется более удобным, если вам легче получить ответ.
Решение
Я думаю, что это зависит от вас или вашей команды 🙂
Так что — нормально писать
/**
* @return boolean
*/
для класса B, или вы можете просто использовать следующий тег:
/**
* {@inheritdoc}
*/
Что означает, что метод имеет то же описание, что и родительский.
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineinheritdoc.pkg.html
Другие решения
Нет смысла иметь функцию a () в B
public function a() {
// Do some extra stuff
// ...
// Then hand it over to the parent
return parent::a();
}
Потому что когда есть экземпляр B, он на самом деле имеет функцию a (), которая ссылается на метод своего родителя a ().
Кстати, когда вы определяете функцию, которая переопределяет метод ее родителя, вам лучше предложить свою документацию в ее docblock. Потому что у вас может быть другой возврат или сделать что-то еще в нем.