How to document macro-generated classes using Doxygen?

Question

I use macros to generate classes as follows:

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 complex and uses various Boost.Preprocessor macros. Is there a way to automatically document generated classes using Doxygen by adding comments to the .h generator or, alternatively, to create an example class with documentation? I tried to enable ENABLE_PREPROCESSING and MACRO_EXPANSION, but that doesn't seem to be enough.

Answer 1

This will not work. The Doxygen preprocessor does not actually perform the full inclusion of the file (it only looks at the included files for macro definitions, otherwise the ENABLE_PREPROCESSING directive will be completely useless!). Therefore, #include "generator.h" not valid.

If you physically replace the #include directive with the contents of the included file, this will work. (Not very useful, I know).

Another way to do this is to modify your files as follows:

generator.h:

 #define DEFCLASS class CLASS_NAME : public parent \ { \ ... whatever ... \ }; 

myclass.h:

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

but this will not work if you use DEFCLASS more than once for the source file (probably a Doxygen error / defect).

Answer 2

At the time I'm writing, Doxygen will perform full-blown file inclusion if several conditions are met. From the Doxygen documentation documentation :

... the preprocessor parses, but doesn’t actually include the code when it encounters #include (with the exception of #include found inside {...})

Another undocumented, but intuitive precondition that I found through experimentation is that any {...} block #include must itself be documented. For example, running Doxygen in the following test file using Boost.Preprocessor will generate entries for the structures FOO::A , FOO::B and FOO::C , provided that MACRO_EXPANSION included in the configuration file, the required extraction mode is set to " All objects ", and the acceleration folder is correctly set to 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 structures in an anonymous namespace will result in a lack of documentation. So, if you can port #include "generator.h" to an explicit namespace, it will work.

Answer 3

What about the "Documentation elsewhere" pararaph at http://www.stack.nl/~dimitri/doxygen/docblocks.html

 /*! \class CLASS_NAME \brief An auto generated class A more detailed class description. */ /*! \fn CLASS_NAME::CLASS_NAME() \brief Default constuctor */ 

Answer 4

I would recommend putting the generated classes in a separate title and just documenting the title. In the best case, the generated classes are more detailed.

Another option would be to script something up. Either using your favorite scripting language, or something like cheetah will not be scary.

I assume your generator looks somewhat simple to generate a stove or boiler features or something else.

 GENERATE_CLASS(Foo); GENERATE_CLASS(Bar); 

Something like this is pretty reasonable grep meat.