Doxygen 不区分 `union myname` 和 `struct myname`

Question

我编写了一个小型矩阵库，作为我正在进行的一个更大项目的一部分。零成本转置很重要，所以我使用/滥用了工会。代码本身可以正常工作（在下面提供），但是在使用 Doxygen 进行文档处理时，它将struct matrix_r 和 union matrix_r 的所有文档合并到一个项目中。也就是说，只有struct matrix_r 和struct matrix_c 的生成页面，但是这两个页面将matrix_r 和matrix_c 描述为联合，具有连接的@brief 文本和连接的属性（来自结构和联合声明）。

我对 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.
*/

直接来自manual，这里有一些其他命令：

这里使用特殊命令\class来表示注释 块包含类测试的文档。其他结构 命令是：

\struct 记录一个 C 结构。

\union 记录一个联合。

\enum 记录枚举类型。

\fn 记录一个函数。

\var 记录变量或 typedef 或枚举值。

\def 记录一个#define。

\typedef 记录类型定义。

\file 记录一个文件。

\namespace 记录命名空间。

\package 记录一个 Java 包。

\interface 记录 IDL 接口。

---

编辑： 我相信这就是 Doxygen 设计的工作方式。见 此处的文档： http://www.doxygen.nl/autolink.html 在“typedefs”部分。它说：

涉及类、结构和联合的类型定义，例如

typedef struct StructName TypeName

为 StructName 创建一个别名，以便生成链接到 StructName，当遇到 StructName 本身或 TypeName 时。

Doxygen 认为 union 标签名称是“真实的”， 不是 typedef （它被认为是“真实的 事情”）。我推荐这个：

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