Hi,
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
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?
I think the pros you mentioned outweigh the cons. I currently have a
patch[1] for MW-Codesniffer to recognize methods with "@inheritDoc" (but
not when surrounded by braces) as documented and not flag them.
[1]
https://gerrit.wikimedia.org/r/#/c/353623/
-- Kunal