Page MenuHomePhabricator

Upgrade Doxygen (to enable INHERIT_DOCS for methods from parent classes)
Closed, ResolvedPublic

Description

Filing this here, since I'm not sure if it's a configuration bug or upstream bug, and it's worth tracking either way.

Doxygen says, " If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the documentation from any documented member that it re-implements. The default value is: YES."

This is explicitly set in maintenance/Doxyfile, but I'm not sure if this is the same Doxyfile we use for doc.wikimedia.org (but hopefully it is).

It doesn't seem to work, e.g.:

The above is missing docs for methods like "select()"

.. which are inherited from Database, and shown at:

https://doc.wikimedia.org/mediawiki-core/master/php/classWikimedia_1_1Rdbms_1_1Database.html#a3b03dd27f434aabfc8d2d639d1e5fa9a

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptDec 6 2016, 3:42 AM
Restricted Application added a project: Documentation. · View Herald TranscriptDec 6 2016, 3:43 AM
Anomie added a subscriber: Anomie.Mar 22 2019, 2:46 PM

Looks like this was a Doxygen bug which was recently fixed upstream in https://github.com/doxygen/doxygen/commit/d763a8c1f6c73982ae83ddd3b390528b3e00770e.

It was released in Doxygen 1.8.16. Our current Debian channel (Stretch) packages 1.8.13. But, someone has already made and published a Doxygen 1.18.16 package in the experimental channel (https://packages.debian.org/experimental/doxygen). Perhaps this can be backported?

Krinkle edited subscribers, added: apaskulin; removed: Mattflaschen-WMF.

Tagging CPT as team I suspect would be most interested in seeing this get deployed. Tagging RelEng as owner of the doc1001 server.

Krinkle updated the task description. (Show Details)Oct 20 2019, 6:01 PM
Krinkle updated the task description. (Show Details)
WDoranWMF added a subscriber: WDoranWMF.

Untagging Core Platform Team as @apaskulin is tagged as a watcher to track.

Krinkle added a subscriber: hashar.

Talked with @hashar. While the CI container and Dockerfile is managed by RelEng, the package itself comes directly from the prod apt repo.

Tagging ServiceOps: Would it be possible to build (or re-use from debian/experimental) Doxygen 1.8.16 to eg buster-wikimedia component/doxygen for use in CI?

Krinkle renamed this task from Doxygen method docs are not inherited (only when abstract classes are involved?) to Upgrade Doxygen (to enable INHERIT_DOCS for methods from parent classes).Oct 23 2019, 6:55 PM
Joe added a subscriber: Joe.EditedOct 23 2019, 6:59 PM

@Krinkle given it's a CI container, why not install doxygen with pip (properly frozen) instead of importing a package?

EDIT: nevermind, I confused softwares. Doxygen needs a proper build as it's in C++.

So we'd need to backport the package - I'd rather recommend the use of a build container (or a multi-stage build) to obtain the software, but we can try a simple rebuild probably.

A backport of the package made available as a component would fit nicely. If we follow what we do for other CI containers we would so something like:

Dockerfile.template
FROM {{ "docker-registry.wikimedia.org/wikimedia-buster" | image_tag }}

USER root
RUN echo "deb http://apt.wikimedia.org/wikimedia stretch-wikimedia component/doxygen" \
    > /etc/apt/sources.list.d/buster-doxygen.list \
    && {{ "doxygen" | apt_install }}

USER nobody
ENTRYPOINT ["doxygen"]

Which is super easy :] If an upgrade is needed later on:

  • build the new Debian package
  • upload to apt
  • bump image changelog
  • docker-pkg
  • done \o/

Happy to do the CI container/config stuff once a package is around (either upstream or in our magic repo).

hashar closed this task as Resolved.Dec 13 2019, 6:20 PM
hashar claimed this task.

We are now using Doxygen 1.8.16 and the documentation for the master branch has been regenerated. I took the example from this task https://doc.wikimedia.org/mediawiki-core/master/php/classWikimedia_1_1Rdbms_1_1DatabaseMysqli.html and it shows a nice drop down list:

:]

All documentations will eventually be regenerated as part of unbreaking the server side PHP search page. T218233