Doxygen не делает различий между `union myname` и`struct myname`

Question

Я написал небольшую матричную библиотеку как часть большого проекта, над которым я работаю. Было важно иметь транспонирование с нулевой стоимостью, поэтому я использовал / злоупотреблял профсоюзами. Сам код работает нормально (приведен ниже), но когда он пришел к документу с Doxygen, он объединяет всю документацию для обоих struct matrix_r а также union matrix_r в один элемент. То есть есть только сгенерированные страницы для struct matrix_r а также struct matrix_c, но эти две страницы описывают matrix_r и matrix_c как объединения, с объединенным @brief текстом и объединенными атрибутами (как из объявлений struct, так и из union).

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

#include <stddef.h>

/// @brief internal stuct for row-major matrices
struct matrix_r {
    int *data; ///< raw pointer backing matrix
    size_t m;  ///< the number of rows
    size_t n;  ///< the number of cols
};

/// @brief internal struct for col-major matrices
struct matrix_c {
    int *data; ///< raw pointer backing matrix
    size_t n;  ///< the number of cols
    size_t m;  ///< the number of rows
};

/// @brief user-facing typedef for row-major matrices
typedef union {
    struct matrix_r id;   ///< identity view of matrix
    struct matrix_c tr;   ///< transposed view of matrix
    int*            flat; ///< flattened view of matrix
} matrix_r;

/// @brief user-facing typedef for row-major matrices
typedef union {
    struct matrix_c id;   ///< identity view of matrix
    struct matrix_r tr;   ///< transposed view of matrix
    int*            flat; ///< flattened view of matrix
} matrix_c;

Answer 1

Структурные команды начинаются с обратной косой черты (\), или же (@) сопровождается именем команды и одним или несколькими параметрами. Например, если вы хотите задокументировать класс Test, вы могли бы поместить следующий блок документации куда-нибудь во входные данные, которые читает doxygen:

/*! \class Test
    \brief A test class.

    A more detailed class description.
*/

Прямо из руководства, вот некоторые другие команды:

Здесь специальная команда \class используется, чтобы указать, что блок комментария содержит документацию для класса Test. Другие структурные команды:

\ struct для документирования C-структуры.

\ союз, чтобы зарегистрировать союз.

\ enum для документирования типа перечисления.

\ fn для документирования функции.

\ var для документирования переменной или typedef или значения перечисления.

\ def для документирования #define.

\ typedef для документирования определения типа.

\ файл для документирования файла.

\ namespace для документирования пространства имен.

\ package для документирования пакета Java.

\ интерфейс для документирования интерфейса IDL.

---

Изменить: я считаю, что именно так Doxygen предназначен для работы. Смотрите документацию здесь: http://www.doxygen.nl/autolink.html в разделе "typedefs". Это говорит:

Typedefs, которые включают в себя классы, структуры и союзы, такие как

typedef struct StructName TypeName

создайте псевдоним для StructName, чтобы ссылки были сгенерированы на StructName при обнаружении либо самого StructName, либо TypeName.

Doxygen считает имя тега объединения "реальной вещью", а не typedef (который рассматривается как псевдоним "реальной вещи"). Я бы порекомендовал это:

/*!@brief The documentation of the union Name*/ 
typedef union Name 
{ 
    //..... 
}Name;