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

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

3 голосов
/ 24 октября 2011

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

Пример: 

#define ATTRIBUTES \
X(TITLE,    "title") \
X(FILENAME, "filename") \
X(GENRE_ID, "genre_id")

enum ATTRIBUTES_ENUM {
  #define X(a, b) a##_ATTRIBUTE,
  ATTRIBUTES
  #undef X
  ATTRIBUTES_COUNT
};

И добавив что-то вроде: 

/**
 * \def TITLE_ATTRIBUTE
 * The media's title.
 */

не работает.

EDIT Благодаря Томасу Мэтьюсу, вот решение, которое я использовал: 

#define ATTRIBUTES \
X(TITLE,    "title")    /*!< title attribute */ \
X(FILENAME, "filename") /*!< filename attribute */ \
X(GENRE_ID, "genre_id") /*!< genre id attribute */

#define X(a, b) a##_ATTRIBUTE,

enum ATTRIBUTES_ENUM {
  ATTRIBUTES
  ATTRIBUTES_COUNT
};

#undef X

И скажи Doxygen, чтобы расширять макросы. Единственным недостатком является то, что комментарий для последнего элемента также используется в качестве комментария для определения ATTRIBUTES. Но это небольшая проблема в моем случае.

1 Ответ

4 голосов
/ 25 октября 2011

Попробуйте следующее

  1. В файле конфигурации Doxygen скажите, чтобы он обрабатывал макросы.

  2. В определении макроса добавьте комментарии Doxygen после каждого члена:

    #define ATTRIBUTES \  
X(TITLE, "title") /**!< title element */ \  
X(FILENAME, "filename") /**!< file name element */ \  
X(GENRE_ID, "genre_id") /**!< title element */

Из-за проблем с форматированием кода комментариями в каждой строке должны быть комментарии типа C.

Насколько я понимаю, Doxygen следуетобработать макрос (сделать замены), а затем передать измененный текст в его механизм комментариев.

Только предположение.

Я настоятельно рекомендую другую схему для преобразования перечислений в текст.Используйте либо массив, вектор или карту.Например: 

enum Attributes_Enum
{
  TITLE, FILENAME, GENRE
};

struct Enum_Text_Entry
{
    enum Attributes_Enum value;
    const char * text;
};

Enum_Text_Entry  Enum_To_Text[] =
{
    {TITLE, "title"},
    {FILENAME, "filename"},
    {GENRE, "genre"},
};

const unsigned int NUMBER_OF_ENTRIES =
sizeof(Enum_To_Text) / sizeof(Enum_To_Text[0]);

Теперь просто найдите в таблице перечисление и прочитайте текст.Хорошая вещь в соединении значения enum и текста в структуре состоит в том, что это позволяет изменять значения enum, но остальная часть кода не должна изменяться.

...