用Doxygen或类似文件记录枚举标志

Question

我刚刚将Doxygen添加到我的工具集中，虽然我对大多数技术感到满意，但我对如何记录枚举标记感到有点困惑（一般情况下也适用于文档，有或没有Doxygen） 。鉴于以下课程：

class foo
{
   /// @enum  Options
   /// @brief Specifies options for the object. Options are combined using
   ///        the bitwise OR operator e.g. "OPTION1 | OPTION2".
   enum Options
   {
   OPTION1 = 1, //< Option 1 description.
   OPTION2 = 2, //< Option 2 description.
   OPTION3 = 4  //< Option 3 description.
   };

   /// @brief Does something.
   /// @param options  Specifies options.
   void bar(int options) {/* Do something */}
};

如何向用户指示如何使用条形函数的options参数？参数的类型为int，而不是Options，因此参数和枚举之间没有直接链接。如果参数是Options类型，那么文档将链接到枚举的描述，这是我想要的行为。

Answer 1

所以让参数类型为Options。您可以编写返回Options的重载运算符来处理&和|以及您需要的任何其他逻辑运算符。

Answer 2

使用“指定选项”记录名为options的变量不是一个有意义的注释。变量名称已经说明了您现有的评论所说的内容。所以让你的评论有意义：

/// @brief Does something.
/// @param options  Specifies options for the object, which must be a bitwise OR
///                 of zero or more of the bit flags in enum foo::Options.
void bar(int options) {/* Do something */}