What part of the doxygen configuration (Doxyfile) is recommended for version control?

Question

Doxygen does not need all configuration tags to be explicitly defined. It will fallback to the default configuration for a tag if undefined.

In a scenario where the documentation is generated with possibly (slightly) different doxygen versions, I wonder which part of the configuration file should be put under version control.

I would prefer that the configuration put in VCS was "parsed"/generated by doxygen using an existing configuration file. The generated output can be controlled with the command line options -x, -u and -s. Using the "parsed" configuration file simplifies comparisons after future updates because the order of tags and formatting is stable.

• Only the differences to the default configuration (can be generated with doxygen -x [configName]).
  • Benefits: It is explicit, what tags should deviate from the default configuration.
  • Downside: In case the default configuration changes (with a new doxygen version), the resulting configuration will differ unexpectedly.
• The documentation without comments (can be generated with doxygen -s -u [configName]).
  • Benefits: All tags are defined. Resulting configuration does not change if a default configuration changes.
  • Downside: Updates in the default values are not applied automatically by using a newer doxygen version. For example an update of the default value for MATHJAX_VERSION would not be applied if already explicitly defined. A workaround may be to explicitly define those tags empty which shall dynamically use the current default value. It seems to work, but I could not find evidence in the documentation that this is a feature.
• Using the "full" documentation (can be generated with doxygen -u [configName]).
  • Benefits: Same as for -s -u. In addition to that: In case the description of a tag changes, this will be visible in VCS. This can be helpful if the meaning has changed and the configuration must be adjusted therefore.
  • Downsides: Same as for -s -u. In addition to that: Irrelevant changes may occur in comments. This is noise in the VCS.

So the question is: Is it recommended to version the full configuration (-u), the one without comments (-u -s) or the minimal one containing only deviations to the default configuration (-x)?

This question is based on doxygen version 1.9.3.

Answer 1

Use the complete documentation without comments. That is parse the existing documentation with

doxygen -s -u [configName]

Define those tags, where you want to dynamically use the current default value, as empty.

This is the most explicit documentation and not prone to noise when the comments to tags would change. It should be reasonable to assume, that the meaning of tags do not change (at least within minor version updates).