¿Cómo documentar clases macrogeneradas con Doxygen?

Question

que usar macros para generar clases de la siguiente manera:

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" 

La clase real es más complicado y utiliza varios Boost. Macros de preprocesador. ¿Hay alguna manera de documentar automáticamente las clases generadas con Doxygen agregando comentarios a generator.h, o alternativamente generar una clase de ejemplo con documentación? Intenté habilitar ENABLE_PREPROCESSING y MACRO_EXPANSION, pero esto no parece ser suficiente.

Answer 1

No funcionará. El preprocesador Doxygen realmente no realiza la inclusión completa del archivo (solo se ve en los archivos incluidos para las definiciones de macro, de lo contrario, la directiva ENABLE_PREPROCESSING sería totalmente inútil). Entonces, el #include "generator.h" no tiene ningún efecto.

Si reemplaza físicamente la directiva #include con el contenido del archivo incluido, funcionará. (No es muy útil, lo sé).

Otra manera de hacerlo es modificar los archivos de la siguiente manera:

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 

pero esto no va a funcionar si use DEFCLASS más de una vez por archivo fuente (probablemente un error/defecto de Doxygen).

Answer 2

¿Qué hay de "Documentación en otros lugares" pararaph en 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 3

Recomendaría poner las clases generadas en un encabezado separado y solo documentar el encabezado. En el mejor de los casos, las clases generadas son más un detalle de implementación.

La otra opción sería algo de script. Usar tu lenguaje de scripting favorito o algo como cheetah no sería terrible.

Supongo que su generador parece algo simple para generar placa de caldera o rasgos o lo que sea.

GENERATE_CLASS(Foo); 
GENERATE_CLASS(Bar); 

Algo así es bastante razonable grep forraje.

Answer 4

En el momento en que escribo, Doxygen hará para realizar la inclusión completa de archivos, siempre que se cumplan un par de condiciones. Desde el Doxygen internals documentation:

... analiza el preprocesador, pero en realidad no incluye el código cuando se encuentra con un # include (con la excepción de # include encontrado en el interior { ...} bloques)

La otra condición indocumentada, pero intuitiva que he encontrado a través de la experimentación es que cualquier cosa {...} bloquean la # include es en sí misma debe ser documentado. Por ejemplo, ejecutar Doxygen en el siguiente archivo de prueba utilizando Boost.Preprocessor generará entradas para las estructuras FOO::A, FOO::B y FOO::C, siempre que MACRO_EXPANSION esté habilitado en el archivo de configuración, el modo de extracción deseado esté configurado en "Todas las entidades" y la carpeta de impulso está en posición correcta en 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() 
} 

sin embargo, la eliminación de FOO para colocar las estructuras en un espacio de nombres en el anonimato dará lugar a ninguna documentación. Entonces, si puede soportar el #include "generator.h" dentro de un espacio de nombres explícito, funcionará.