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

Question

我编写了一个小型矩阵库，作为我正在进行的一个更大项目的一部分。零成本转换很重要，所以我使用/滥用了 union 。代码本身工作正常(在下面提供)，但是当涉及到使用 Doxygen 的文档时，它结合了 struct matrix_r 和 union matrix_r< 的所有文档 成一个单一的项目。也就是说，只有 struct matrix_r 和 struct matrix_c 生成的页面，但这两个页面将 matrix_r 和 matrix_c 描述为 union ，具有连接的 @brief 文本和连接的属性(来自结构和 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 ，您可以将以下文档 block 放在 doxygen 读取的输入中的某处:

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

    A more detailed class description.
*/

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

Here the special command \class is used to indicate that the comment block contains documentation for the class Test. Other structural commands are:

\struct to document a C-struct.

\union to document a union.

\enum to document an enumeration type.

\fn to document a function.

\var to document a variable or typedef or enum value.

\def to document a #define.

\typedef to document a type definition.

\file to document a file.

\namespace to document a namespace.

\package to document a Java package.

\interface to document an IDL interface.

---

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

Typedefs that involve classes, structs and unions, like

typedef struct StructName TypeName

create an alias for StructName, so links will be generated to StructName, when either StructName itself or TypeName is encountered.

Doxygen 认为 union 标签名是“真正的东西”，不是 typedef(它被认为是“真实的”的别名东西”)。我推荐这个:

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