phpDocumentor不会覆盖父类的文档

2023年10月2日 202次阅读

所以,基本上我有以下设置：

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},但我想要有完全相反的行为.

最佳答案 你期望在你的例子中看到的正是应该发生的事情 – A :: foo()应该显示“这是一些文档”而B :: foo()应该显示“这个文档比类更具体一个”.如果没有发生,那就是一个错误.请在
https://github.com/phpDocumentor/phpDocumentor2开一个问题.

顺便说一句,{@inheritdoc}的意图是将A :: foo()的长描述嵌入B :: foo()整体文档的中间位置.通过在B :: foo()的docblock中有描述,你可以覆盖B :: foo()自动继承的A :: foo()信息的正确默认行为. {@inheritdoc}标签是专门创建的,因此您有机会为B :: foo()编写描述,并且仍然能够包含A :: foo()中的描述.您在B :: foo()的docblock中放置{@inheritdoc}意味着您可以准确控制A：foo()的描述将出现在B的整体描述中.

我在{@inheritdoc}中看到的绝大多数用法都是人们认为它必须仅用于从父级继承描述和标签的地方.我认为这是由于phpDoc 1.x中的错误实现,其中自然继承无法正常工作,因此人们认为必须使用标签,即使它仍然没有给他们所追求的东西.

点赞