Как документировать сгенерированные макросами классы с Doxygen? - PullRequest
Новая
       31

Как документировать сгенерированные макросами классы с Doxygen?

7 голосов
/ 20 сентября 2011

Я использую макросы для генерации классов следующим образом:

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"

Фактический классболее сложный и использует различные макросы Boost.Preprocessor.Есть ли способ автоматически задокументировать сгенерированные классы с помощью Doxygen, добавив комментарии в generator.h, или в качестве альтернативы сгенерировать пример класса с документацией?Я попытался включить ENABLE_PREPROCESSING и MACRO_EXPANSION, но этого недостаточно.

Ответы [ 4 ]

4 голосов
/ 17 сентября 2012

В то время, когда я пишу, doxygen будет выполнять полноценное включение файла, если выполняется пара условий.Из документации по внутренним документам doxygen :

... препроцессор анализирует, но фактически не включает код, когда встречается с #include (за исключением найденного #includeвнутри {...} блоков)

Другое недокументированное, но интуитивное предварительное условие, которое я обнаружил в ходе экспериментов, заключается в том, что любой {...} блок, в котором находится #include, должен сам по себе бытьдокументированы.Например, при запуске doxygen в следующем тестовом файле с использованием Boost.Preprocessor будут сгенерированы записи для структур FOO::A, FOO::B и FOO::C, при условии, что в файле конфигурации включен MACRO_EXPANSION,желаемый режим извлечения установлен на «Все сущности», а папка надстройки правильно установлена ​​в 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()
}

Однако удаление FOO для размещения структур в анонимном пространстве имен приведет кнет документацииТак что, если вы можете вынести #include "generator.h" в явном пространстве имен, оно будет работать.

1 голос
/ 20 сентября 2011

Это не сработает.Препроцессор Doxygen на самом деле не выполняет полноценное включение файла (он ищет только во включенных файлах определения макросов; в противном случае директива ENABLE_PREPROCESSING была бы совершенно бесполезной!).Таким образом, #include "generator.h" не имеет никакого эффекта.

Если вы физически замените директиву #include содержимым включенного файла, она будет работать.(Не очень полезно, я знаю).

Другой способ сделать это - изменить ваши файлы следующим образом:

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

, но это не будет работать, если вы используете DEFCLASS более одного раза для исходного файла (вероятно, ошибка / дефект Doxygen).

1 голос
/ 20 сентября 2011

Я бы порекомендовал поместить сгенерированные классы в отдельный заголовок и просто документировать заголовок.В лучшем случае сгенерированные классы - это больше детали реализации.

Другой вариант - что-то в сценарии.Либо использовать ваш любимый язык сценариев, либо что-то вроде cheetah не было бы ужасно.

Я предполагаю, что ваш генератор выглядит чем-то простым для генерации котельной пластины или признаков или чего-то еще. 

GENERATE_CLASS(Foo);
GENERATE_CLASS(Bar);

Что-то в этом роде - довольно разумный корм grep.

1 голос
/ 20 сентября 2011

А как насчет пункта "Документация в других местах" в 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
*/
...