Explanation of "warning: ignoring unsupported tag" logs

[kaycebasques]

Hi, just documenting this for other fellow rules_doxygen users that might be encountering the issue. Long story short, presumably this happens when:

• You specify a partial Doxygen configuration in your doxygen Bazel rule
• You use an older version of Doxygen than what rules_doxygen assumes (e.g. we use v1.9 and rules_doxygen might assume v1.14)

See https://issues.pigweed.dev/issues/384047922#comment3 for further explanation.

The fix in our case is to provide a full Doxyfile configuration to rules_doxygen so that it doesn't need to guess at what values to configure.

[kaycebasques]

@TendTo feel free to close this whenever you see fit

[TendTo]

Yes, you are right. To be precise, the issue is that the default Doxyfile I provide has been produced by the default version of doxygen the rules use, which is 1.14.0 at the moment. You can actually see the doxygen version used to generate the default Doxyfile in its very first line

rules_doxygen/doxygen/Doxyfile.template

Line 1 in 79751df

# Doxyfile 1.14.0

Every version of doxygen usually adds a couple of new tags, which are obviously unknown to older versions. Hence, when the Doxyfile is parsed, an harmless warning for each of the unknown flags gets produced.

Personally, I don't mind, and this solution allows the Doxyfile to support both new and old versions with the latest default flags, but if it becomes annoying and you know exactly the doxygen version you want to use, then the solution is exactly what you did: provide provide a Doxyfile that matches your version, so that it will contain only the flags available for that version with their default values.

To let this be useful to other users, before adding it in the documentation, let me also be explicit on the steps needed to fix it. Just generate the Doxyfile with the using the doxygen version of choice

doxygen -g

add these lines at the end of the output file

# {{INPUT}}

# {{DOT_PATH}}

# {{ADDITIONAL PARAMETERS}}

# {{OUTPUT DIRECTORY}}

so that they can be replaced by the values you provide to the rule and finally move the file to wherever you see fit and add it to your doxygen rule

load("@doxygen//:doxygen.bzl", "doxygen")

doxygen(
    name = "doxygen",
    srcs = ["README.md"] + glob([
        "*.h",
        "*.cpp",
    ]),
    doxyfile_template = "Doxyfile"
)

See this example for more information on how to provide a custom Doxyfile.

[TendTo]

Actually, I was thinking that I may provide a bunch of Doxyfile for the most common versions, with a fallback on the latest version's Doxyfile.
The problem is that only works if I'm able to detect doxygen's version, which can be easy or hard depending on the configuration in the MODULE.bazel, and it must be clear if that doxygen version has a corresponding Doxyfile or is going to resort to the fallback.