search

phpDocumentor / fig-standards

Standards either proposed or approved by the Framework Interop Group
http://www.php-fig.org/
Other
361 stars 85 forks source link

Traits and docblock inheritance. #128

Closed ghost closed 5 years ago

ghost commented 8 years ago

Hello

I have a question regarding docblock inheritance for methods: are docblocks inherited from trait methods? For example, if class C uses trait T, where T defines method foo (with docblock) and C also defines foo (without docblock), does the foo from C inherit the docblock from T? In a certain way, traits are code that is injected into the class, so in essence the original trait method "disappears" from the equation as soon as it's redefined in the class itself, so would docblocks not be inherited in this case?

Similarly, if method foo in trait T does not specify a docblock and C now extends parent class P, which also defines a foo, does the foo from the trait also inherit documentation from the foo in P (and hence, can it use things such as {@inheritDoc} for this purpose)? Using the same logic as above, that would also be the case.

(I accidentally already posted this in the PSR-5 pull request, my apologies.)

Thanks in advance

ashnazg commented 5 years ago

When it comes to docblock inheritance, I believe it is generally assumed that when you override a method without providing a new docblock, you are implying that your override method still meets the documentation in the original method... and thus, your override method should inherit the original docblock.

This opinion would apply to any element that implements/extends/inherits in the code.