Каково соглашение для тега @return, если метод переопределяет и возвращает результат метода родителя?

Question

Если у меня есть метод в некотором классе, который возвращает логическое значение, например

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или что он возвращает "значение родителя" и обращается к родителю за документацией? Или что-то другое?

С точки зрения написания второй вариант кажется более разумным, так как, если изменяется возвращаемое значение родителя, это не повлечет за собой изменений в других частях документации. С точки зрения чтения, первый вариант кажется более удобным, если вам легче получить ответ.

Answer 1

Нет смысла иметь функцию a() в B

public function a() {
    // Do some extra stuff 
    // ... 

    // Then hand it over to the parent 
    return parent::a();
}

Потому что когда есть экземпляр B, он на самом деле имеет функцию a(), которая ссылается на метод своего родителя a().

Кстати, когда вы определяете функцию, которая переопределяет метод ее родителя, вам лучше предложить свою документацию в ее docblock. Потому что у вас может быть другой возврат или сделать что-то еще в ней.

Answer 2

Я думаю, что это зависит от вас или вашей команды:)

Так что - нормально писать

/**
 * @return boolean
 */

для класса B, или вы можете просто использовать следующий тег:

/**
 * {@inheritdoc}
 */

Что означает, что метод имеет то же описание, что и родительский. http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineinheritdoc.pkg.html