On Sun, May 14, 2017 at 12:43 AM, Ryan Kaldari <rkald...@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
> http://usejsdoc.org/tags-inheritdoc.html.
>
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
_______________________________________________
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
