On Sun, May 14, 2017 at 12:43 AM, 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).
It would be nice to check compatibility with major tools. For example, some
years ago PHPStorm did automatic description inheritance (which is
recommended by most documentation standards) but did not recognize
@inheritdoc so adding it to methods effectively prevented users from seeing
the documentation. (These days it works fine either way.)
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."
This does not mean what one would assume at first glance. In PhpDocumentor
terminology, the summary is the part of the freeform text that ends with
the first empty line or the first period followed by newline. (Some other
tools call this the short description.) The rest of the freeform text
(until the first non-inline tag) is called the description. Inline tags are
recognized in the description but not the summary. So
/**
* Recticulates the splines.
*
* {@inheritdoc}
*
* This class recticulates everything twice.
*/
will result in
Recticulates the splines.
<parent doc here>
This class recticulates everything twice.
but
/**
* {@inheritdoc}
*
* This class recticulates everything twice.
*/
will result in
{@inheritdoc}
This class recticulates everything twice.
PSR-5, the (stalled) draft standard for documentation recognizes both tag
and inline inheritdoc, and I expect most tools these days follow suit.
{@inheritdoc} can be used to extend parent documentation, and the
alternatives are not so great (copy the full documentation and modify it,
which leads to maintainability problems and documentation rot, or only
document what's different in the child, in which case the full details will
never be seen by most users as most tools don't expose parent
documentation). Granted, pulling in the parent documentation and wrapping
it with local one is a bit awkward, but that can be helped with some sane
convention. E.g.
* Parent documentation:
* {@inheritdoc}
*
* Changes for this child:
* ...
(Of course this won't really be helpful for people using less sophisticated
IDEs, text editors, or github lookup to check the documentation. I wonder
what fraction of our developer base does that.)
Information about the use of @inheritdoc in JavaScript can be found at
Most Wikimedia projects use JSDuck, not JSDoc. At a glance there is not
much difference [2], although JSDoc declares explicitly that it will copy
parent documentation even if there is no @inheritdoc and it's unclear
whether JSDuck does that. Neither seems to support inline use.
[1]
https://github.com/php-fig/fig-standards/blob/master/
proposed/phpdoc.md#61-making-inheritance-explicit-using-the-inheritdoc-tag
[2]
https://github.com/senchalabs/jsduck/wiki/@inheritdoc