Thanks for raising this question, I was thinking about something similar a little while back when I was reviewing some code without the explicit @inheritdoc on it.
I personally think we'll gain a lot more if we stick to always documenting our methods, including @inheritdoc. Reasoning below. On Sat, May 13, 2017 at 3:43 PM, Ryan Kaldari <[email protected]> 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.) > Another reason to always document with @inheritdoc is that it makes all of us get used to always provide documentation. When it is missing, we'll look for the reason why - and that can help us spot missing documentation (and get used to explain our code) in general, and as an instinctive practice. It's like adding comments for forcing-ignore on jslint and phpcs - simply by having to write the ignore rule itself (and justify it to reviewers), you're forcing yourself to consider whether that particular solution is the best one. Maybe you could've done it differently while sticking to the style, and you can produce better code. This happens often, and having to write those comments is sometimes the best indicator. The same, in my opinion, can happen if we insist on outputting all methods with a documentation. We make sure that we all get used to writing documentation and feeling its absence if it's not there, and we're forced to explain our reasoning for other developers, and learning to expect proper documentation when we review. Even if you're inheriting a method, sometimes there's a good reason to explain whatever minor changes are done, or if you are intentionally doing something different than the parent. In my experience, when we gloss over these things as "eh, it's just inheriting the parent" we sometimes miss things we should have still documented, and I think that is worse than having to "waste" a couple of lines of comment code. > > Some arguments for not using it: > * It isn't necessary for generating docs at doc.wikimedia.org (Doxygen > automatically inherits method docs if available). > By the way, I'm not entirely sure that's true for jsdoc? I think it expects @inheritdoc? I am not sure, I may have missed the explanation in the link you provided. > * It would require adding thousands of extra comment blocks to our code to > implement it consistently. > Slight repetition from my point above -- yes, it would cost us about 3 lines of comment per inherited method, but the gain of getting used to reading comments and having our code set up with the expectation of everything being documented, in my opinion, is worth it. Moriel > > 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. > _______________________________________________ > Wikitech-l mailing list > [email protected] > https://lists.wikimedia.org/mailman/listinfo/wikitech-l -- No trees were harmed in the creation of this post. But billions of electrons, photons, and electromagnetic waves were terribly inconvenienced during its transmission! _______________________________________________ Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
