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, resulting in the method having no documentation in the output.
I see three possible fixes:
- Re-standardize on @inheritdoc.
- Add "inheritDoc=\inheritdoc" to ALIASES in every Doxyfile.
- 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.
: 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.