On 05/13/2017 03:43 PM, Ryan Kaldari wrote:
A question that came up during Documentation Day was
whether or not we
should use the @inheritdoc convention for indicating that methods are
documented in parent classes (rather than leaving them blank).
Some arguments for using it include:
* It can help code-sniffers and linters know that the documentation isn't
* It lets humans who are looking at the code know that they can find
and about 40 times in core PHP. It's also used in at least 19 production
Some arguments for not using it:
* It isn't necessary for generating docs at doc.wikimedia.org
automatically inherits method docs if available).
* It would require adding thousands of extra comment blocks to our code to
implement it consistently.
What are people's opinions on using it?
I think the pros you mentioned outweigh the cons. I currently have a
patch for MW-Codesniffer to recognize methods with "@inheritDoc" (but
not when surrounded by braces) as documented and not flag them.