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记录这个时，它在类B的方法foo()中显示"This is some documentation"，然而我希望它说"这份文档比类A的更加具体"。在phpDocumenter 1中，一切看起来都和预期一样。

那么，这里发生了什么？这是phpDocumentor2的新默认行为吗？如果是，有没有办法改变它？还是这只是一个bug？

注意：在研究过程中，我经常遇到{@inheritDoc}，但我想要完全相反的行为。

- Seba

Answer 1

您期望在示例中看到的正是应该发生的事情——A::foo() 应该显示"This is some documentation"，而 B::foo() 应该显示"This documentation is way more specific than in class A"。如果没有这样的情况发生，那么这就是一个错误。请在https://github.com/phpDocumentor/phpDocumentor2上开启一个问题(issue)。

另外，{@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中存在错误实现，导致自然继承无法正确工作，因此人们认为必须使用该标记，即使它仍然不能给他们想要的结果。

- ashnazg