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

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

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.