Doxygen для эмуляции шаблона C

Я без особого успеха пытаюсь сгенерировать документацию с использованием Doxygen для эмулированных шаблонов на C. Я надеюсь, что кто-то знает, как заставить макросы работать в препроцессоре doxygen? Я уже безуспешно пытался включить MACRO_EXPANSION.

РЕДАКТИРОВАТЬ: Наиболее денатурированная форма этого вопроса будет: «Как я могу заставить Doxygen обрабатывать директиву препроцессора #include аналогично препроцессору C?»

У меня в папке "test" есть следующий код (очень надуманный пример):

templates.h

#ifndef TEMPLATES_H_
#define TEMPLATES_H_

#define CAT(X,Y) X##_##Y
#define TEMPLATE(X,Y) CAT(X,Y)

#endif // TEMPLATES_H_

test.h

#ifndef TEST_H_
#define TEST_H_

#include "templates.h"

#ifdef TEST_T
#error "TEST_T cannot be defined prior to this compilation step"
#endif

#define TEST_T uint8_t
#include "test_template.h"
#undef TEST_T

#define TEST_T uint16_t
#include "test_template.h"
#undef TEST_T

#endif // TEST_H_

test_template.h

#ifdef TEST_T

#include "templates.h"

TEST_T TEMPLATE(sum,TEST_T)(TEST_T a, TEST_T b);

#endif // ifdef TEST_T

test.c

#include "test.h"

#ifdef TEST_T
#error "TEST_T cannot be defined prior to this compilation step"
#endif

#define TEST_T uint8_t
#include "test_template.c"
#undef TEST_T

#define TEST_T uint16_t
#include "test_template.c"
#undef TEST_T

test_template.c

#ifdef TEST_T

TEST_T TEMPLATE(sum,TEST_T)(TEST_T a, TEST_T b)
{
   return a + b;
}

#endif // ifdef TEST_T

В моем файле конфигурации doxygen:

test.cfg

# Doxyfile 1.8.13

PROJECT_NAME           = "Test"
OUTPUT_DIRECTORY       = "docs_test"
TAB_SIZE               = 3
OPTIMIZE_OUTPUT_FOR_C  = YES
INPUT                  = "../test"
RECURSIVE              = YES
MACRO_EXPANSION        = YES

# Temporary to extract all without tags
EXTRACT_ALL            = YES

Однако шаблонные версии функции sum * отсутствуют в doxygen (документация .h или .c); например, test.h находится ниже (хотя я был бы также рад, если бы он появился в test_template.h вместо этого):

вывод doxygen для test.h

Есть предположения?


person Squirrel    schedule 23.02.2017    source источник
comment
Примечание: Убедитесь, что у вас есть завершающие символы новой строки в файлах, когда вы выполняете макросы.   -  person user694733    schedule 28.02.2017
comment
Ценная записка. Лично у меня всегда есть новая строка по привычке (черта, которую выучили из систем, давно прошла), но она не отображается в приведенных выше фрагментах кода.   -  person Squirrel    schedule 28.02.2017


Ответы (1)


Из документации doxygen: http://www.doxygen.nl/manual/preprocessing.html

Если вы не уверены, каков будет эффект предварительной обработки doxygen, вы можете запустить doxygen следующим образом:

doxygen -d Препроцессор

Это заставит doxygen выгружать источники ввода в стандартный вывод после завершения предварительной обработки (Подсказка: установите QUIET = YES и WARNINGS = NO в файле конфигурации, чтобы отключить любой другой вывод).

Сравните это с выводом, сгенерированным реальным препроцессором c, чтобы убедиться, что расширение doxygen действительно соответствует тому, что видит компилятор C.

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

При этом и как отмечали другие, я бы лично не использовал препроцессор C таким образом, но я согласен, что это вопрос личного мнения.

Возможная проблема, которая возникает: препроцессор C может генерировать код при раскрытии макросов, но он не будет генерировать комментарии, и вся разметка doxygen встроена в комментарии C. .

Конечно, doxygen может обнаружить, что существует функция с именем sum_uint8_t, но для того, чтобы действительно добавить документацию по этой функции, исходный код должен будет явно добавить «структурные команды» в исходный код.

См. http://www.doxygen.nl/manua/docblocks.html#structuralcommands

person Marc Alff    schedule 28.02.2017
comment
Как ни странно, я не могу заставить doxygen сбрасывать источники ввода с помощью -d Preprocessor. Я обеспечил ENABLE_PREPROCESSING = YES, QUIET = YES и WARNINGS = NO. Странно, я буду продолжать возиться с этим. В ответ на пункт о том, что препроцессор не вставляет комментарии, стоит остерегаться этого. На этом этапе, когда в моей конфигурации EXTRACT_ALL = YES, я считаю, что он все еще должен отображать их в документации (только без комментариев). - person Squirrel; 04.03.2017