Since the prechecker results for plugins are now public, and they show hundreds of errors for one of my plugins, I thought I'd look into these for the next release. (Hardly any of these errors would ever affect the user, so you might say the whole point is rather moot, but I thought I might want to do some cleanup nevertheless.)
About 70% of these errors relate to PHPDoc. Some of them are legitimate, but one main point seems to be that the checker complains about absent PHPDoc comments for overridden methods (when the intention is to retain the comment from the parent method).
Now I'm certainly not going to copy the PHPDoc from the superclass down to a dozen of subclasses just to please the automated checker - that would be possible but outright stupid.
The developer docs say on this issue:
An exception is made for overridden methods which make no change to the meaning of the parent method and maintain the same arguments/return values. In this case you should omit the comment completely. Use of the @inheritdoc or @see tags is explicitly forbidden as a replacement for any complete docblock.
How do I make the the prechecker recognize this?
I do not see it as a big issue for two pragmatic reasons.
- I always try and amend/extend the documentation so that it applies specifically to the implementation of my method, and how it differs from the parent, or how it implements the abstract behaviour. So I need some description anyway.
- With regards to the method signature, as a human programmer, I also work with one file at a time. And it is actually more useful for me to have the documentation available directly in my editor window rather than having to skip through the chain of the documentation inheritance.
Well, one of my method is called "get_id()". It returns an id string associated with the class/object. This is documented in the parent class and subclasses override it (typically with a one-liner). What should I usefully extend about that PHPDoc block?
Regarding your second point, Eclipse does that for me.
It's certainly not a big problem - I just need to ignore the prechecker results - but as Tim says, it's very annoying. i don't like programing "for the tools" rather than for the user or reader.
Maybe one way out would be to allow the @inheritdoc tag (though that would be more of a workaround).