15. November 2020 4 min read

Use CI to prevent additional Doxygen warnings in your project

This is the second in series of articles where I discuss how to avoid increasing number of warnings over time in your documentation build. In previous article I wrote about Sphinx documentation build, but now I will write how to limit Doxygen warnings. What usually happens is that you forget to comment few members, but because that is a Doxygen warning you skip it for later stage. Not long, the list of un-commented and not documented members starts increasing out of control without any indication.
The solution is in your Continuous Integration pipelines. No matter what you use for building, from GitHub Actions, to GitLab CI, Travis CI, Circle CI, ... there is always a place for the command line tool, that will fail your build when number of warnings is higher (or lower) then expected. Warnings-plugin by Melexis is a project I help maintain that is designed to fail your pipeline if number of warnings is higher or lower than expected.

Setup warnings limit for Doxygen builds

First you need to install the tool through pip in your CI file (or just install it in your Docker container)

pip3 install mlx.warnings

Plugin has two options of usage. The easiest is with command line option, where you add your Doxygen build command right after with minimum and maximum number of warnings allowed (or you can use exact number of warnings flag). That basically means any change in number of Doxygen warnings now fails the build. I even have a tendency to make them environment variables, so that they can be different among different stages of the project (maybe development has more/less warnings than release), but you can start with hard-coding.

Fail your build when there are less than 5 Doxygen warnings:

mlx-warnings --doxygen --min-warnings 5 --command doxygen doxyfile

Fail your build when there are more than 5 Doxygen warnings:

mlx-warnings --doxygen --max-warnings 5 --command doxygen doxyfile

Fail your build when there are not 5 Doxygen warnings

mlx-warnings --doxygen --exact-warnings 5 --command doxygen doxyfile

The second option is that you use the json file. That option is mostly helpful when you have a library that is shared between number of projects and you do not want to set limits in each of the projects, but simply forward the json file from the library to your command. Then content of the json file located in your library would be:

{
    "doxygen": {
        "enabled": true,
        "min": 5,
        "max": 5
    },
}

and the command for the library documentation build would be:

mlx-warnings --config path/to/library/config.json --command doxygen doxyfile

There you are, it is this simple to avoid adding additional warnings to your Doxygen builds and enable only positive progress in your project. Set foundation for your projects to be warning free today and command line Melexis Warnings Plugin will eventually help you get there.