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 <rkaldari(a)wikimedia.org>
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
Wikitech-l(a)lists.wikimedia.org
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!