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 _______________________________________________ Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
