c++ - 如何使用 Doxygen 注释生成的代码

Question

我正在使用 C 预处理器生成枚举中的元素。有没有办法为生成的元素编写 doxygen 注释？我不能在 doxygen 之前通过预处理器运行它，因为那样会去除 doxygen 注释。

例子:

#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注释:

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

由于代码格式问题，每行的注释应为 C 风格注释。

我的理解是 Doxygen 应该处理宏(进行替换)，然后将修改后的文本提供给它的注释引擎。

虽然只是猜测。

我强烈建议使用不同的模式将枚举转换为文本。使用数组、 vector 或映射。如:

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]);

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