Page MenuHomePhabricator

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


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 (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:

Event Timeline

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 ( 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)
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

@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:

FROM {{ "" | image_tag }}

USER root
RUN echo "deb 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 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 and it shows a nice drop down list:

doxygen_inherit_docs.png (267×789 px, 38 KB)


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