Hi!
What are people's opinions on using it?
I think it's OK to use it in relevant cases (along with already existing
and used @see) and recognize such uses as documented, but making it
mandatory would look like increasing busywork for a doubtful benefit of
making robots (e.g. syntax checkers) not bother us with warnings. Since
I see the purpose of robots to make _less_ busywork, this seems to be
counter-productive.
For the benefit of humans, if they're reading generated docs, doc
generators should be already able to handle inheritance? If they're
reading raw code @inheritdoc provides marginal benefit of reminding to
look into parent method, but most people probably would do it anyway if
child method does not have docs.
I am not sure I find the argument "it ensures docs are not forgotten"
that convincing - if no docs meaning "same docs as parent", then there's
nothing to forget - there is always documentation inheritance by default
(of course, if parent is not documented, this is not true, but
@inheritdoc does not fix that) so putting @inheritdoc is just saying
"yes, use default" - thus defeating the purpose of having the default!
And if the method needs more docs that just the default (e.g. child does
something special), the habit of putting @inheritdoc everywhere does not
help - on the contrary, since @inhertidoc, at least as defined by JS, is
exclusive, it means to add some content one will have to work extra,
thus lowering the probability of it happening.
Also, some code now uses params/return tags in child code but the doc
text only in parents (presumably so that it'd be easier for IDEs?).
@inheritdoc as defined by Javascript means "ignore the rest of the tags"
- but that's not what most IDEs would do. So there's a potential that
different systems would read different tags (shouldn't make a difference
but might still). Not sure how that would work? If combining @inheritdoc
with other content works as Gergo described, it may be helpful, but
still not sure what exactly it would happen.
--
Stas Malyshev
smalyshev(a)wikimedia.org