Документирование макросы с использованием Doxygen

Question

/** @brief This is my initial struct. */ 
typedef struct 
{ 
    f32 v; /**< Value. */ 
    int32 s; /**< Scale. */ 
} f32_t; 

#define DECLARE_TYPE(N) \ 
     typedef f32_t q##N##_t; /**< This is my Q struct. */ 

DECLARE_TYPE(31) 
DECLARE_TYPE(25) 

Приведенный выше код объявляет q31_t и q25_t структур. Я хотел бы документировать их с помощью Doxygen, но все, что я пробовал, структуры не отображаются в документации. Их даже не упоминают. Исходная структура f32_t является единственной документированной.

Можно ли это исправить?

Answer 1

Основная проблема, похоже, заключается в размещении комментария документации в макросе. Я нахожу, что если я поставлю комментарий к документу с помощью макроса invocation, то он будет отражен в сгенерированной документации; иначе это не так. Естественно, вам нужно настроить Doxygen для расширения макросов, что не является поведением по умолчанию.

Например:

/** @brief This is my initial struct. */ 
typedef struct 
{ 
    ae_f32 v; /**< Value. */ 
    ae_int32 s; /**< Scale. */ 
} ae_f32_t; 

#define DECLARE_TYPE(N) \ 
     typedef ae_f32_t ae_q##N##_t 

DECLARE_TYPE(31); /**< @brief This is my Q31 struct */ 
DECLARE_TYPE(25); /**< @brief This is my Q25 struct */ 

(я также переместил с запятой из макроса, но с док комментария также перемещается, это вопрос стиля только.)

Это имеет смысл, поскольку одна из вещей, которые препроцессор делает, - это преобразование комментариев в пробелы. Не очевидно, что Doxygen должен сделать это таким образом, чтобы он игнорировал комментарии к файлам в макросах, но для этого не является необоснованным.