PhpDocumentor не отменяет документы из родительского класса

Question

Таким образом, в основном у меня есть следующие настройки:

class A { 

    /** 
    * This is some documentation 
    */ 
    public function foo() {} 

} 

class B extends A { 

    /** 
    * This documentation is way more specific than in class A 
    */ 
    public function foo() {} 

} 

Когда я пытаюсь задокументировать с phpDocumentor2 отображается на метод Foo() для класса B «Это некоторая документация », однако я бы хотел сказать:« Эта документация более конкретна, чем в классе А ». В phpDocumenter 1 все выглядит так, как ожидалось. Итак, что здесь происходит? Это новое поведение по умолчанию phpDocumentor2? И если да, есть ли способ изменить его? Или это просто ошибка?

Примечание: при выполнении моих исследований я часто сталкивался с {@inheritDoc}, но я хотел бы иметь совершенно противоположное поведение.

Answer 1

То, что вы ожидаете увидеть в своем примере, - это именно то, что должно произойти - A :: foo() должен показать «Это какая-то документация», в то время как B :: foo() должен показать «Эта документация намного больше чем в классе А ". Если этого не происходит, это ошибка. Пожалуйста, откройте вопрос по адресу https://github.com/phpDocumentor/phpDocumentor2.

В качестве стороннего намерения {@inheritdoc} должно быть вложено длинное описание A :: foo() где-то посередине общего документа B :: foo(). Имея описания в docblock B :: foo(), вы можете отменить правильное поведение по умолчанию для информации A :: foo(), которая автоматически унаследована B :: foo(). Тег {@inheritdoc} был создан специально для того, чтобы у вас была возможность написать описание для B :: foo() и по-прежнему включить описание из A :: foo(). Ваше размещение {@inheritdoc} в docblock B :: foo() означало, что вы можете точно определить, где описание A: foo() будет отображаться в общем описании B.

Подавляющее большинство использования, которое я вижу в дикой природе для {@inheritdoc}, - это то, где люди думают, что он должен использоваться только для наследования описаний и тегов от родителя. Я думаю, что это связано с ошибкой реализации в phpDoc 1.x, где естественное наследование работает неправильно, и поэтому люди думали, что у тега есть, хотя он все еще не дал им то, что было после.