PhpDocumentor does not override parent class documents

Question

So basically I have the following setup:

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() {} } 

When I try to document this with phpDocumentor2, it is displayed in the foo () method for class B “This is some documentation”, however I would like to say: “This documentation is more specific than in class A”. In phpDocumenter 1, everything looks as expected. So what is going on here? Is this the new phpDocumentor2 default behavior? And if so, is there a way to change it? Or is it just a mistake?

Note: when doing my research, I often came across {@inheritDoc}, but I would like to have the exact opposite behavior.

Answer 1

What you expect to see in your example is exactly what should happen - A :: foo () should show "This is some kind of documentation", and B :: foo () should show "This documentation is more specific than in class A. " If this does not happen, this is a mistake. Please open the question at https://github.com/phpDocumentor/phpDocumentor2 on it.

As a third-party intent, {@inheritdoc} would include a long description of A :: foo () somewhere in the middle of the general B :: foo () document. By having descriptions in the B :: foo () docblock, you override the correct default behavior for the information A :: foo (), which is automatically inherited by B :: foo (). The {@inheritdoc} tag was created specifically for you to be able to write a description for B :: foo () and still include the description from A :: foo (). Your placement of {@inheritdoc} in B :: foo () docblock meant that you can control exactly where the description of A: foo () will appear in the general description of B.

The vast majority of the use that I see in the wild for {@inheritdoc} is where people think that it should only be used to inherit descriptions and tags from the parent. I think this is due to an implementation error in phpDoc 1.x, where natural inheritance does not work correctly, and therefore people thought that this tag should be used, although it still did not give them what came after.