Как Doxygen обрабатывает включение в объявления enum - PullRequest
Новая
       67

Как Doxygen обрабатывает включение в объявления enum

2 голосов
/ 28 октября 2019

У нас есть несколько C-проектов, ориентированных на системы с ограниченными ресурсами, которые сильно зависят от перечислений, определенных с помощью макросов препроцессора в специальных файлах ресурсов. Эти файлы включаются в определение enum.

Эта концепция используется для того, чтобы пользователь нашего API "имел право только" редактировать файл определения ресурса, но не нужно прикасаться к файлу заголовка, где эти перечисления фактически определены. Кроме того, он также позволяет генерировать строки для этих событий.

Пример для файла ресурсов 

DEF_SOME_EVENT_TYPE(EVENT_ALERT)
DEF_OTHER_EVENT_TYPE(EVENT_OTHER_ALERT)
DEF_SOME_EVENT_TYPE(EVENT_FLASH)
DEF_SOME_EVENT_TYPE(EVENT_BEEP)

Пример для соответствующего определения перечисления 

enum some_event_e
{
  #define DEF_SOME_EVENT_TYPE(name) name,
  #define DEF_SOME_OTHER_EVENT_TYPE(name)
  #include "resource_definitions.g"
  #undef DEF_SOME_EVENT_TYPE
  #undef DEF_SOME_OTHER_EVENT_TYPE 
  SOME_EVENT_COUNT
};

enum some_other_event_e
{
  #define DEF_SOME_EVENT_TYPE(name) name,
  #define DEF_SOME_OTHER_EVENT_TYPE(name)
  #include "resource_definitions.g"
  #undef DEF_SOME_EVENT_TYPE
  #undef DEF_SOME_OTHER_EVENT_TYPE 
  SOME_OTHER_EVENT_COUNT
};

При попыткедокументируя перечислители, кажется, что doxygen неправильно расширяет эти макросы и включает файл определения ресурса.

Предположим, у нас есть следующий блок документации : 

/*! 
  @enum some_event_e
  @brief Some event identifiers
*/

/*!
  @var some_event_e::EVENT_ALERT
  @brief alert event
*/

/*!
  @var some_event_e::SOME_EVENT_COUNT
  @brief Total number of some events
*/

Doxygen правильно документирует SOME_EVENT_COUNT, но выдаст предупреждение для EVENT_ALERT. 

warning: documented symbol 'some_event_e::EVENT_ALERT' was not declared or defined.

ENABLE_PREPROCESSING и MACRO_EXPANSION оба установлены на YES в Doxyfile иЯ добавил *.g (расширение файла, используемое для определений ресурсов) к INCLUDE_FILE_PATTERNS и добавил его к EXTENSION_MAPPING через g=C. Я использую doxygen версии 1.8.16.

Есть ли способ документировать значения перечисления, объявленные таким образом? В некоторых случаях действительно полезно использовать этот видмакро-магия для определения перечислений, поэтому было бы очень полезно, если бы можно было документировать их с помощью doxygen.

...