Inherit documentation from interface

Question

I use docblocks for documenting function methods, classes... the usual.

I found myself using the adapter pattern, as such, all my adapters implement a common interface and return the same things.

The common interface has all the functions documented with their names, return values, variables .etc.

Is there a way to make the entire adapter class's functions inherit the documentation from the same functions in the common interface? I am aware of @inheritDoc however I am unsure if one needs to use it for every function or if can be applied to the class docblock or if that is entirely a bad idea.

Sort of new to "real" documentation.

Answer 1

Documentation generators and IDEs these days generally know how to do this inheritance for you. Just by not having a docblock on the adapters functions, the docs of the interface's functions should be automatically inherited. Sometimes, if you do make a child docblock, the parent gets ignored... but generally anything interpreting docblocks these days has better logic for merging the child docblock info with the parent docblock info, and presenting it as one block of info for the given function.

The @inheritdoc tag has been frequently misused to try to accomplish this same thing, but has never actually been for that purpose. This tag has one job alone -- to control where in a child doc to display the parent's Long Description. That's it, that's all, nothing else.