use of @inheritdoc

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

use of @inheritdoc

Ryan Kaldari-2
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).

Some arguments for using it include:
* It can help code-sniffers and linters know that the documentation isn't
missing.
* It lets humans who are looking at the code know that they can find
documentation elsewhere.
* We are already using it. (It appears over 200 times in core JavaScript
and about 40 times in core PHP. It's also used in at least 19 production
extensions.)

Some arguments for not using it:
* It isn't necessary for generating docs at doc.wikimedia.org (Doxygen
automatically inherits method docs if available).
* It would require adding thousands of extra comment blocks to our code to
implement it consistently.

What are people's opinions on using it?

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."

Information about the use of @inheritdoc in JavaScript can be found at
http://usejsdoc.org/tags-inheritdoc.html.
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: use of @inheritdoc

Moriel Schottlender
Thanks for raising this question, I was thinking about something similar a
little while back when I was reviewing some code without the explicit
@inheritdoc on it.

I personally think we'll gain a lot more if we stick to always documenting
our methods, including @inheritdoc. Reasoning below.

On Sat, May 13, 2017 at 3:43 PM, Ryan Kaldari <[hidden email]>
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).
>
> Some arguments for using it include:
> * It can help code-sniffers and linters know that the documentation isn't
> missing.
> * It lets humans who are looking at the code know that they can find
> documentation elsewhere.
> * We are already using it. (It appears over 200 times in core JavaScript
> and about 40 times in core PHP. It's also used in at least 19 production
> extensions.)
>

Another reason to always document with @inheritdoc is that it makes all of
us get used to always provide documentation.
When it is missing, we'll look for the reason why - and that can help us
spot missing documentation (and get used to explain our code) in general,
and as an instinctive practice.

It's like adding comments for forcing-ignore on jslint and phpcs - simply
by having to write the ignore rule itself (and justify it to reviewers),
you're forcing yourself to consider whether that particular solution is the
best one. Maybe you could've done it differently while sticking to the
style, and you can produce better code. This happens often, and having to
write those comments is sometimes the best indicator.

The same, in my opinion, can happen if we insist on outputting all methods
with a documentation.

We make sure that we all get used to writing documentation and feeling its
absence if it's not there, and we're forced to explain our reasoning for
other developers, and learning to expect proper documentation when we
review.
Even if you're inheriting a method, sometimes there's a good reason to
explain whatever minor changes are done, or if you are intentionally doing
something different than the parent.

In my experience, when we gloss over these things as "eh, it's just
inheriting the parent" we sometimes miss things we should have still
documented, and I think that is worse than having to "waste" a couple of
lines of comment code.


>
> Some arguments for not using it:
> * It isn't necessary for generating docs at doc.wikimedia.org (Doxygen
> automatically inherits method docs if available).
>

By the way, I'm not entirely sure that's true for jsdoc? I think it expects
@inheritdoc? I am not sure, I may have missed the explanation in the link
you provided.


> * It would require adding thousands of extra comment blocks to our code to
> implement it consistently.
>

Slight repetition from my point above -- yes, it would cost us about 3
lines of comment per inherited method, but the gain of getting used to
reading comments and having our code set up with the expectation of
everything being documented, in my opinion, is worth it.

Moriel


>
> What are people's opinions on using it?
>
> 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."
>
> Information about the use of @inheritdoc in JavaScript can be found at
> http://usejsdoc.org/tags-inheritdoc.html.
> _______________________________________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l




--
No trees were harmed in the creation of this post.
But billions of electrons, photons, and electromagnetic waves were terribly
inconvenienced during its transmission!
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: use of @inheritdoc

Prateek Saxena
I agree with Moriel, being explicit helps during reviews and when you
read your own code after a month.

On Sun, May 14, 2017 at 4:58 AM, Moriel Schottlender <[hidden email]> wrote:
> By the way, I'm not entirely sure that's true for jsdoc? I think it expects
> @inheritdoc? I am not sure, I may have missed the explanation in the link
> you provided.

I tested, and it does not require @inheritdoc. The documentation that
Ryan linked to says, "By default, if you do not add a JSDoc comment to
a symbol, the symbol will inherit documentation from its parent."

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: use of @inheritdoc

Bartosz Dziewoński
On Sun, May 14, 2017 at 7:32 AM, Prateek Saxena <[hidden email]>
wrote:

>
> On Sun, May 14, 2017 at 4:58 AM, Moriel Schottlender <[hidden email]>
> wrote:
> > By the way, I'm not entirely sure that's true for jsdoc? I think it
> expects
> > @inheritdoc? I am not sure, I may have missed the explanation in the link
> > you provided.
>
> I tested, and it does not require @inheritdoc. The documentation that
> Ryan linked to says, "By default, if you do not add a JSDoc comment to
> a symbol, the symbol will inherit documentation from its parent."
>

Note that we actually use a different tool to generate our documentation –
it's not JSDoc, it's JSDuck. In my experience it requires @inheritdoc at
least for properties, see e.g.
https://phabricator.wikimedia.org/rGOJU0fad0c89b1f918e556db1687d45f2eb8bdfa25dc
(the
behavior might differ for methods, I haven't tested it recently). We do
have a proposal to switch to JSDoc though:
https://phabricator.wikimedia.org/T138401 .


--
Matma Rex
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: use of @inheritdoc

Gergo Tisza
In reply to this post by Ryan Kaldari-2
On Sun, May 14, 2017 at 12:43 AM, Ryan Kaldari <[hidden email]>
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
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: use of @inheritdoc

Legoktm
In reply to this post by Ryan Kaldari-2
Hi,

On 05/13/2017 03:43 PM, Ryan Kaldari 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).
>
> Some arguments for using it include:
> * It can help code-sniffers and linters know that the documentation isn't
> missing.
> * It lets humans who are looking at the code know that they can find
> documentation elsewhere.
> * We are already using it. (It appears over 200 times in core JavaScript
> and about 40 times in core PHP. It's also used in at least 19 production
> extensions.)
>
> Some arguments for not using it:
> * It isn't necessary for generating docs at doc.wikimedia.org (Doxygen
> automatically inherits method docs if available).
> * It would require adding thousands of extra comment blocks to our code to
> implement it consistently.
>
> What are people's opinions on using it?

I think the pros you mentioned outweigh the cons. I currently have a
patch[1] for MW-Codesniffer to recognize methods with "@inheritDoc" (but
not when surrounded by braces) as documented and not flag them.

[1] https://gerrit.wikimedia.org/r/#/c/353623/

-- Kunal

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: use of @inheritdoc

Stas Malyshev
In reply to this post by Ryan Kaldari-2
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
[hidden email]

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: use of @inheritdoc

Brian Wolff
On Thursdy, May 18, 2017, Stas Malyshev <[hidden email]> wrote:

> 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.


Sometimes its not that obvious if the class introduces new methods which
are documented. In the past ive been bitten by the docs for db being in
IDatabase, when i didnt think to look beyond the abstract base class. As
someone who only reads docs in source, i think @inheritdoc is a useful
reminder.

--
bawolff
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: use of @inheritdoc

Jeroen De Dauw-2
Hey,

Personally I'm not using this in my projects and would object to those tags
being added as they are IMO clutter. Those projects have some relevant
differences with MediaWiki that all contribute to those tags being more
clutter than helpful:

* Good OO: small classes and interfaces, favoring of composition over
inheritance and thus very rarely inheriting concrete code
* Simple well named methods with no or few parameters: documentation
explaining something beyond type is seldomly needed
* Usage of scalar type hints, nullable type hints and return type hints via
usage of PHP 7.1

And of course following any of those points has benefits way beyond not
needing inheritdoc tags as crutch.

Cheers

--
Jeroen De Dauw | https://entropywins.wtf | https://keybase.io/jeroendedauw
Software craftsmanship advocate
~=[,,_,,]:3
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: use of @inheritdoc

Max Semenik
Meanwhile, I've encountered another problem that supports the point that we
need to document functions, this or another way: Phan barfs about functions
using Database::selectField().[1] I've suppressed the warnings for now, but
would like a more permanent solution.


-----
[1]
https://integration.wikimedia.org/ci/job/mwext-php70-phan-jessie/2199/console

On Fri, May 19, 2017 at 3:12 AM, Jeroen De Dauw <[hidden email]>
wrote:

> Hey,
>
> Personally I'm not using this in my projects and would object to those tags
> being added as they are IMO clutter. Those projects have some relevant
> differences with MediaWiki that all contribute to those tags being more
> clutter than helpful:
>
> * Good OO: small classes and interfaces, favoring of composition over
> inheritance and thus very rarely inheriting concrete code
> * Simple well named methods with no or few parameters: documentation
> explaining something beyond type is seldomly needed
> * Usage of scalar type hints, nullable type hints and return type hints via
> usage of PHP 7.1
>
> And of course following any of those points has benefits way beyond not
> needing inheritdoc tags as crutch.
>
> Cheers
>
> --
> Jeroen De Dauw | https://entropywins.wtf | https://keybase.io/jeroendedauw
> Software craftsmanship advocate
> ~=[,,_,,]:3
> _______________________________________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l
>



--
Best regards,
Max Semenik ([[User:MaxSem]])
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l