如何 Doxygen 注释生成的代码

Question

我正在使用 C 预处理器在枚举中生成元素。有没有办法为生成的元素编写 doxygen cmets？我不能只在 doxygen 之前通过预处理器运行它，因为这会剥离 doxygen cmets。

例子：

#define ATTRIBUTES \
X(TITLE,    "title") \
X(FILENAME, "filename") \
X(GENRE_ID, "genre_id")

enum ATTRIBUTES_ENUM {
  #define X(a, b) a##_ATTRIBUTE,
  ATTRIBUTES
  #undef X
  ATTRIBUTES_COUNT
};

并添加如下内容：

/**
 * \def TITLE_ATTRIBUTE
 * The media's title.
 */

没用。

编辑 感谢 Thomas Matthews，这是我使用的解决方案：

#define ATTRIBUTES \
X(TITLE,    "title")    /*!< title attribute */ \
X(FILENAME, "filename") /*!< filename attribute */ \
X(GENRE_ID, "genre_id") /*!< genre id attribute */

#define X(a, b) a##_ATTRIBUTE,

enum ATTRIBUTES_ENUM {
  ATTRIBUTES
  ATTRIBUTES_COUNT
};

#undef X

并告诉 Doxygen 扩展宏。唯一的缺点是最后一个元素的注释也用作ATTRIBUTES 定义的注释。但这对我来说只是个小问题。

Answer 1

试试下面的

1. 在 Doxygen 配置文件中，告诉它处理宏。

2. 在宏定义中，在每个成员之后添加 Doxygen cmets：

   #define ATTRIBUTES \  
   X(TITLE, "title") /**!< title element */ \  
   X(FILENAME, "filename") /**!< file name element */ \  
   X(GENRE_ID, "genre_id") /**!< title element */  
   

由于代码格式问题，每行的cmets应该是C sytle cmets。

我的理解是 Doxygen 应该处理宏（进行替换），然后将修改后的文本输入到它的评论引擎中。

不过只是猜测。

我强烈建议使用不同的架构将枚举转换为文本。使用数组、向量或映射。如：

enum Attributes_Enum
{
  TITLE, FILENAME, GENRE
};

struct Enum_Text_Entry
{
    enum Attributes_Enum value;
    const char * text;
};

Enum_Text_Entry  Enum_To_Text[] =
{
    {TITLE, "title"},
    {FILENAME, "filename"},
    {GENRE, "genre"},
};

const unsigned int NUMBER_OF_ENTRIES =
sizeof(Enum_To_Text) / sizeof(Enum_To_Text[0]);

现在只需在表中搜索枚举并读出文本。将枚举值和文本放在一个结构中的好处是它允许枚举值更改，但其余代码不必更改。