Документирование условного эксклюзивного кода в Doxygen - PullRequest
Новая
       9

Документирование условного эксклюзивного кода в Doxygen

0 голосов
/ 06 января 2019

Рассмотрим 

// EXTERNAL_MACRO is an external macro defined to some value by build system

#if EXTERNAL_MACRO == 1
#   define EXCLUSIVE_MACRO_ONE
#elif EXTERNAL_MACRO == 2
#   define EXCLUSIVE_MACRO_TWO
#else
#   define EXCLUSIVE_MACRO_OTHER
#endif

Во время сборки определен только один из макросов EXCLUSIVE_MACRO _...

Как один документ все три макроса EXCLUSIVE_MACRO _... в Doxygen?

PREDEFINED параметр конфигурации для этого не полезен, поскольку он позволяет определять EXTERNAL_MACRO только для одного значения (и, следовательно, документировать только одно EXCLUSIVE_MACRO _...).

Этот ответ SO предлагает обходное решение, которое выполняет свою работу, но требует дополнительной логики. Я ищу более простой ответ, который использует конфигурацию Doxygen (если возможно), а не модифицирует исходный код (хотя некоторые изменения, конечно, подходят).

Ответы [ 2 ]

0 голосов
/ 09 января 2019

Вдохновленный ответом .

ПРОБЛЕМА : у нас есть существующий заголовок, который на основе внешнего макроса (предоставляемого системой сборки) определяет один из нескольких исключительных макросов во время компиляции. Поскольку определен только один из макросов времени компиляции (для каждой отдельной сборки), трудно добавить документацию Doxygen ко всем исключительным параметрам. 

// DEFINED_EXTERNALLY is a macro provided by the build system (e.g. via -D). It is defined as 1, 2, or some other natural number.

// Based on DEFINED_EXTERNALLY we want to define one of several exclusive DEFINED_HERE_... macros (e.g. DEFINED_HERE_1, DEFINED_HERE_2, and DEFINED_HERE_OTHER).

// First, we check that none of the DEFINED_HERE_... macros is defined yet.
#if defined(DEFINED_HERE_1) || defined(DEFINED_HERE_2) || defined(DEFINED_HERE_OTHER)
#   error "Conflict: macro DEFINED_HERE_... is already defined!"
#endif

// Then, we define one, and only one, of the DEFINED_HERE_... macros.
#if DEFINED_EXTERNALLY == 1
#   define DEFINED_HERE_1
#elif DEFINED_EXTERNALLY == 2
#   define DEFINED_HERE_2
#else
#   define DEFINED_HERE_OTHER
#endif

РЕШЕНИЕ : Мы временно определяем все варианты макросов DEFINED_HERE _... вместе с их документацией. Это заставит Doxygen сгенерировать документацию для всех из них. Затем мы отменяем определение всех вариантов и возобновляем нормальную логику определения макроса. В результате у нас будет документация по всем вариантам, но во время компиляции будет определен только один из них, как это было до добавления документации.

Оригинальный код 

// DEFINED_EXTERNALLY is a macro provided by the build system (e.g. via -D). It is defined as 1, 2, or some other natural number.

// Based on DEFINED_EXTERNALLY we want to define one of several DEFINED_HERE_... macros (e.g. DEFINED_HERE_1, DEFINED_HERE_2, and DEFINED_HERE_OTHER).

// First, we check that none of the DEFINED_HERE_... macros is defined yet.
#if defined(DEFINED_HERE_1) || defined(DEFINED_HERE_2) || defined(DEFINED_HERE_OTHER)
#   error "Conflict: macro DEFINED_HERE_... is already defined!"
#endif

Новый вставленный код для создания документации 

/// \brief Value 1.
/// \details It does the following...
#define DEFINED_HERE_1
#undef DEFINED_HERE_1
/// \brief Value 2.
/// \details It does the following...
#define DEFINED_HERE_2
#undef DEFINED_HERE_2
/// \brief Other value.
/// \details It does the following...
#define DEFINED_HERE_OTHER
#undef DEFINED_HERE_OTHER

Оригинальный код 

// Then, we define one, and only one, of the DEFINED_HERE_... macros.
#if DEFINED_EXTERNALLY == 1
#   define DEFINED_HERE_1
#elif DEFINED_EXTERNALLY == 2
#   define DEFINED_HERE_2
#else
#   define DEFINED_HERE_OTHER
#endif

Примечание: никаких изменений в настройках Doxygen по умолчанию не требуется. 

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = NO
EXPAND_ONLY_PREDEF     = NO
PREDEFINED             =
EXPAND_AS_DEFINED      =
0 голосов
/ 07 января 2019

См. Связанный вопрос и ответ: Документирование макроса конфигурации с помощью doxygen

В основном:

В файле конфигурации doxygen добавьте: 

PREDEFINED = IN_DOXYGEN

Где-нибудь в исходном коде добавить: 

/*
  Exporting build configuration macros to doxygen,
  so they get documented.
*/
#ifdef IN_DOXYGEN
#   define EXCLUSIVE_MACRO_ONE
#   define EXCLUSIVE_MACRO_TWO
#   define EXCLUSIVE_MACRO_THREE
#endif /* IN_DOXYGEN */

Затем документация для этих макросов собрана правильно.

Если вы не хотите менять источник, вы можете добавить EXCLUSIVE_MACRO_ONE и друзей в PREDEFINED вместо настройки EXTERNAL_MACRO.

...