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.