phpDocumentor does not override docs of parent class

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 displays at method foo() for class B "This is some documentation", however I'd like it to say " This documentation is way more specific than in class A". In phpDocumenter 1, everything looks like expected. So, what is going on here? Is this the new default behavior of phpDocumentor2? And if so, is there a way to change it? Or is this simply a bug?

Note: while doing my research, I bumped frequently into {@inheritDoc}, but I'd like to have the exact opposite behavior.

Answer 1

What you are expecting to see in your example is exactly what should be happening -- A::foo() should show "This is some documentation" while B::foo() should show "This documentation is way more specific than in class A". If that's not happening, it is a bug. Please open an issue at https://github.com/phpDocumentor/phpDocumentor2 on it.

As an aside, the intent of {@inheritdoc} would be to embed A::foo()'s long description somewhere in the middle of B::foo()'s overall doc. By having descriptions in B::foo()'s docblock, you sort of override the proper default behavior of A::foo()'s info being automatically inherited by B::foo(). The {@inheritdoc} tag was created specifically so that you had the opportunity to write a description for B::foo() and still be able to include the description from A::foo(). Your placement of {@inheritdoc} in B::foo()'s docblock meant you could control exactly where A:foo()'s description would appear in B's overall description.

A vast majority of usage I see in the wild for {@inheritdoc} is where people think that it must be used just to inherit descriptions and tags from a parent. I think this has been due to buggy implementations back in phpDoc 1.x where natural inheritance did not work correctly, and therefore people thought the tag had to be used, even though it still did not give them what they were after.