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 missing. * It lets humans who are looking at the code know that they can find documentation elsewhere. * We are already using it. (It appears over 200 times in core JavaScript and about 40 times in core PHP. It's also used in at least 19 production extensions.)
Some arguments for not using it: * It isn't necessary for generating docs at doc.wikimedia.org (Doxygen 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?
Also, a quick note on usage. A lot of our existing usage looks like "* {@inheritdoc}". As explained at phpdoc.org, this usage is technically incorrect:
"Currently some applications have DocBlocks containing just the {@inheritDoc} inline tag to indicate that their complete contents should be inherited. This usage breaks with the PHPDoc Standard as summaries cannot contain inline tags and inheritance is automatic; you do not need to define a special tag for it. However, it does make clear that an element has been explicitly documented (and thus not forgotten). As such we are working to include a new (normal) tag in the PHPDoc Standard @inheritDoc that will serve that purpose."
Information about the use of @inheritdoc in JavaScript can be found at http://usejsdoc.org/tags-inheritdoc.html.