Re: [Wikitech-l] use of @inheritdoc

[Brian Wolff]

On Thursdy, May 18, 2017, Stas Malyshev  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
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l

Re: [Wikitech-l] Congratulations to accepted candidates for Google Summer of Code 2017 & Outreachy Round 14

[Amrit Sreekumar]

Hello everyone!

I am Amrit Sreekumar from India, at present I am pursuing my B.Tech in
Computer Science at Amrita School of Engineering, kerala. Here I am an
active member of a local FOSS initiative and I will be working on the
improvement of the extension 'proofreadpage' and Wikisource.
By the end of the 3 months of coding phase during the GSoC period, I aim to
implement new features and the mentioned deliverables in
https://phabricator.wikimedia.org/T16. Yann Forget and Thomas Tanon
will be mentoring the task.

-- 
Best regards
Amrit Sreekumar
Amrita University 
GitHub  | Blog

___
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l

Re: [Wikitech-l] use of @inheritdoc

[Stas Malyshev]

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
smalys...@wikimedia.org

___
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l