On Sun, May 14, 2017 at 12:43 AM, Ryan Kaldari rkaldari@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