Page MenuHomePhabricator

Doxygen doesn't handle `@inheritDoc` by default, only `@inheritdoc`
Closed, ResolvedPublic

Description

Doxygen only recognizes the annotation as @inheritdoc, while since rMCSNfd29d61e50bb: Sniff & fix lowercase @inheritdoc we've standardized on @inheritDoc. The end result is that the annotation is ignored, plus this overrides Doxygen's default inheritance,[1] resulting in the method having no documentation in the output.

I see three possible fixes:

  1. Re-standardize on @inheritdoc.
  2. Add "inheritDoc=\inheritdoc" to ALIASES in every Doxyfile.
  3. Push upstream to recognize @inheritDoc, at least for PHP.

I don't think we actually want to do #1, both for the reasons fd29d61e5 chose @inheritDoc and because it would be a huge churn, but it's an option. #3 would probably be the best, assuming upstream is amenable (and SRE doesn't mind making a backported deb so we don't have to wait for bullseye). #2 could be done immediately.

[1]: Note Doxygen also has a bug, recently fixed upstream, which prevents any doc inheritance from a parent class's non-abstract method. That's T152478: Upgrade Doxygen (to enable INHERIT_DOCS for methods from parent classes), not this task, and the fixes proposed for this task won't affect T152478.

Details

Related Gerrit Patches:

Event Timeline

Anomie created this task.Mar 22 2019, 3:13 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptMar 22 2019, 3:13 PM

The simplest upstream fix, if they don't want it to be specific to PHP, would be to just add the mixed-case entry alongside https://github.com/doxygen/doxygen/blob/0776c5491feded1d27e5765051b9170b66f0caad/src/cmdmapper.cpp#L137.

Change 498401 had a related patch set uploaded (by Anomie; owner: Anomie):
[mediawiki/services/parsoid@master] Docs: Add a Doxyfile alias for @inheritDoc

https://gerrit.wikimedia.org/r/498401

Change 498401 merged by jenkins-bot:
[mediawiki/services/parsoid@master] Docs: Add a Doxyfile alias for @inheritDoc

https://gerrit.wikimedia.org/r/498401

At glance, it seems to be like the simplest option would be to standardise on @inheritdoc (option 1) – at least in the short-term.

  • It works in Doxygen (which is the software we primarily write these annotations for).
  • It can work in phpcs (either casing would be hardcoded in our ruleset, we have a simple choice there).
  • It works in various IDEs we know some core contributors use (PHPStorm, NetBeans).

The task description says fd29d61e50bb references reasons not to use @inheritdoc, but I don't see how any of those are relevant here.

  • PSR-5: A theoretical spec that has no direct impact on us. It's a reason to aim for the "common way" in the long-term, by working with Doxygen, and IDE vendors etc. and then consider migrating.
  • Java: MediaWiki is not written in Java.
  • phpDocumentor: We use Doxygen, not phpDocumentor.

I, personally, would push for #3. Ideally not just with a bug report, but an actual pull request. In the meantime we can apply #2 as a temporary workaround. @Legoktm, is it possibly to use our almighty Libraryupgrader to update all Doxyfile?

Change 534631 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] docs: Add support for @inheritDoc (alias for @inheritdoc)

https://gerrit.wikimedia.org/r/534631

Change 534631 merged by jenkins-bot:
[mediawiki/core@master] docs: Add support for @inheritDoc (alias for @inheritdoc)

https://gerrit.wikimedia.org/r/534631

Krinkle closed this task as Resolved.Oct 20 2019, 5:55 PM
Krinkle claimed this task.
Krinkle removed a project: Patch-For-Review.
Krinkle added a subscriber: apaskulin.