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

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

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 «Это некоторая документация», однако я хотел бы сказать: «Эта документация более конкретна, чем в классе A». В phpDocumenter 1 все выглядит так, как и ожидалось. И так, что здесь происходит? Это новое поведение phpDocumentor2 по умолчанию? И если да, то есть ли способ его изменить? Или это просто баг?

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


php phpdoc phpdocumentor2
person Seba    schedule 23.08.2013    source источник

Ответы (1)


arrow_upward
2
arrow_downward

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

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

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

person ashnazg    schedule 26.08.2013