How to document macro-generated classes with Doxygen?

Question

I use macros to generate classes in the following way:

generator.h:

class CLASS_NAME : public parent
{
    //generate variables with names given by CLASS_VARIABLES using complicated
    //Boost.Preprocessor stuff.
};

#undef CLASS_NAME
#undef CLASS_VARIABLES

myclass.h:

#define CLASS_NAME MyClass
#define CLASS_VARIABLES (a, b, c, x, y, z)
#include "generator.h"

The actual class is more complicated and uses various Boost.Preprocessor macros. Is there a way to automatically document the generated classes with Doxygen by adding comments to generator.h, or alternatively to generate an example class with documentation? I have tried enabling ENABLE_PREPROCESSING and MACRO_EXPANSION, but this does not seem to suffice.

Answer 1

At the time I'm writing, doxygen will perform full-blown file inclusion, provided a couple of conditions hold. From the doxygen internals documentation:

...the preprocessor parses, but not actually includes code when it encounters a #include (with the exception of #include found inside { ... } blocks)

The other undocumented, but intuitive precondition I've found through experimentation is that whatever {...} block the #include is in must itself be documented. For instance, running doxygen on the following test file utilizing Boost.Preprocessor will generate entries for structs FOO::A, FOO::B, and FOO::C, provided that MACRO_EXPANSION is enabled in the config file, the desired extraction mode is set to "All Entities", and the boost folder is properly set in INCLUDE_PATH:

#include <boost/preprocessor/iteration/local.hpp>
#include <boost/preprocessor/tuple/elem.hpp>

#define STRUCTS (A, B, C)

namespace FOO {
    #define BOOST_PP_LOCAL_MACRO(n) struct BOOST_PP_TUPLE_ELEM(3,n, STRUCTS) {};
    #define BOOST_PP_LOCAL_LIMITS (0,2)
    #include BOOST_PP_LOCAL_ITERATE()
}

However, removing FOO to place the structs in an anonymous namespace will result in no documentation. So, if you can bear to #include "generator.h" within an explicit namespace, it will work.