Question

假设我有这种结构类型：

typedef struct Hidden Hidden;
struct Hidden
{
    int foo;
    int bar;
};

然后我有一个全局变量

Hidden visible;

绝不应该使用

Hidden，visible应该是Hidden类型的唯一声明。我不想为Hidden生成文档，因为我不希望它被使用，而是生成visible的文档，包含有关它及其字段的所有信息。

我发现的最接近的事情是，当您记录struct没有标签时：

struct
{
    int foo; ///< Number of particals in the universe.
    int bar; ///< Number of socks in the drawer.
} Baz; ///< Nameless struct variable.

Doxygen会产生

struct {
   int foo
       Number of particals in the universe. 
   int bar
       Number of socks in the drawer. 
} Baz
  Nameless struct variable.

这是我想要实现的那种，但我不能使用无名结构。

这样的事情可能吗？

Answer 1

我找到了办法。使用预处理器预定义为@RBE建议允许您仅为doxygen创建代码，无论如何都不会编译。所以这样做（并使DOXYGEN成为预定义的宏）：

typedef struct Hidden Hidden;

#ifdef DOXYGEN

struct
{
    int foo; ///< Number of particals in the universe.
    int bar; ///< Number of socks in the drawer.
} visible; ///< Nameless struct variable!

#endif

struct Hidden
{
    int foo;
    int bar;
};

Hidden visible;

这很黑，但它确实有效。

Answer 2

执行所需操作的最简单方法是使用宏定义在要编译的代码和将运行doxygen的代码之间切换：

#define DOXYGEN

#ifdef DOXYGEN
/**
 *  @brief Describe your visible structure here.
 */
typedef struct VISIBLE
{
    int foo; //< Number of particles in the universe.
    int bar; //< Number of socks in the drawer.
} VISIBLE;
#else
typedef struct HIDDEN
{
    int foo;
    int bar;
} HIDDEN;

HIDDEN visible;
#endif

只需评论或取消注释DOXYGEN定义即可从一个定义切换到另一个定义。

Answer 3

您是否考虑过在没有typedef的情况下声明结构类型？例如，这可能有效：

/**
 * @brief This is a variable that is the only instance of a structure of its kind.
 */
struct Hidden
{
    int foo; ///< Docs
    int bar; ///< Docs
} visible;

您可能还想尝试在声明之外进行记录，如Use doxygen to document members of a c structure outside of the structure definition

中所述

Doxygen - 记录struct变量但不记录struct

3 个答案: