Expand macro inside doxygen comment for printing out software version

Question

I have some C++ code base, documented with doxygen, and build with GNU make. Version information is centralized in makefile, where I have something like:

Answer 1

the commands manual suggests that $(VARIABLE) expands environment variables. So maybe you can put your version in an environment variable?

Answer 2

You need to use the "export" functionality of make ie a very simple make file with

project_name=FooBar
export project_name
all:
    doxygen Doxyfile

Will allow you to use the following comments in C++

/*! \mainpage Project $(project_name) Lorem ipsum dolor

I can see this becoming a PITA with a large set of exports but it's a fairly simple way to do it. Alternatively you could run doxygen from a separate BASH script with all the exports in it to avoid polluting your Makefile too much.

Answer 3

Macros in comments are not generally expanded (see, for example, this answer). This is not unique to doxygen and I can 't think of a way to do this using the PREDEFINED configuration option.

As you state in the question, you can use sed, see the third bullet point in this answer. For example, using the following

INPUT_FILTER  = "sed -e 's/VERSION/1.0/'"

will replace all instances of VERSION with 1.0 in all your source files (you can specify which files to process with INPUT_FILTER, rather than processing all source files). You might not want VERSION to be expanded everywhere, so perhaps it is best to use something like $(VERSION) and sed this token. Also, you will need a way of getting your version number from your makefile and into your doxygen configuration file. This can be done with another sed.

To address your last bullet point, doxygen has the FILE_VERSION_FILTER configuration option for determining the version number of each file. Using this will print some version information (whatever is printed to standard out from the command specified in FILE_VERSION_FILTER) at the top of each file page. In the documentation there are examples of getting the version number using a number of different version control systems. Also, here is a page describing how to use git and doxygen to extract version information.

The only drawback with this configuration option is that I don't know how to specify where the file version information should appear in the final documentation. I presume you can use a layout file: I presume you can change the layout of pages, but I have never done this and don't know how easy it would be to use this to include version information on the mainpage.