7

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.

0

4 Answers 4

5

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.

1
  • I am not sure about your second precondition about documenting the block in which the #include directive lies. I believe it is not needed.
    – Heyji
    Jan 5, 2016 at 13:43
2

What about "Documentation at other places" paragraph in http://www.doxygen.nl/manual/docblocks.html

/*! \class CLASS_NAME
    \brief An auto generated class

    A more detailed class description.
*/

/*! \fn CLASS_NAME::CLASS_NAME()
    \brief Default constuctor
*/
2
  • Hmm, this somehow doesn't work. I can't do it exactly like you proposed because my actual class name is a concatenation of CLASS_NAME and a string. I tried using \class MyClass but then no documentation seems to be generated. Is it maybe because Doxygen searches for MyClass but doesn't find it? I also tried \class CLASS_NAMEConcatenatedString, but again: nothing.
    – AbuBakr
    Sep 23, 2011 at 7:31
  • Than maybe add a forward declaration for that class.
    – Fantastory
    Mar 27, 2019 at 13:09
1

It won't work. The Doxygen preprocessor doesn't really perform full blown file inclusion (it only looks in the included files for macro definitions; otherwise, the ENABLE_PREPROCESSING directive would be totally useless!). So the #include "generator.h" has no effect.

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

Another way to do this is to modify your files like this:

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 per source file (probably a bug/defect of Doxygen).

2
  • I think I can't use your modification because I again use #includes and #defines in my class definition. I could place the #defines in front of the class, but I don't think I can get rid of the #includes...
    – AbuBakr
    Sep 23, 2011 at 7:45
  • As stated by spyderfreek below, if the #include is inside a { } block, the inclusion will work.
    – Heyji
    Jan 5, 2016 at 12:45
1

I would recommend putting the generated classes in a separate header and just documenting the header. In the best case, generated classes are more of an implementation detail.

The other option would be script something up. Either using your favorite scripting language, or something like cheetah wouldn't be terrible.

I am guessing your generator looks something simple to generate boiler plate or traits or whatever.

GENERATE_CLASS(Foo);
GENERATE_CLASS(Bar);

Something like that is pretty reasonable grep fodder.

2
  • I'm not sure if I understand your first paragraph correctly. Do you suggest to create an example header containing preprocessor output? This would only be a good solution if this header could be created automatically. Since I use cmake, this might be possible. I could then create comments in generator.h using sweetrommie's suggestion.
    – AbuBakr
    Sep 23, 2011 at 7:52
  • In the first paragraph, I didn't mean generated output. I meant separating the code into its own header. Then giving executive summary of general use, not specifics of the classes. Another option would be to create a pure virtual interface that all the generated classes "inherit" (whether literally or just mimic) from and document that. If you wanted to generate something, I would use cheetah.
    – Tom Kerr
    Sep 23, 2011 at 14:16

Not the answer you're looking for? Browse other questions tagged or ask your own question.