使用 Doxygen 或类似方法记录枚举标志答案

【问题标题】：Documenting enum flags with Doxygen or similar使用 Doxygen 或类似方法记录枚举标志
【发布时间】：2012-11-18 01:57:42
【问题描述】：

我刚刚将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 */}
};

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

【问题讨论】：

标签： c++ enums documentation doxygen flags

【解决方案1】：

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

【讨论】：

我收到了一些建议，即您不应该将枚举类型用于包含位标志的变量，例如link
除非枚举枚举所有可能的位组合，否则您不能这样做。 Jon Bentley 的枚举只是命名单个选项，而不是所有可能的选项可以组合的方式。
@DavidHammen - 当然可以。普通枚举的底层类型足够大，可以容纳定义值的所有可能组合，并且值的所有组合对枚举都是有效的。 7.2 [dcl.enum]/7 太长，无法在此处引用，但这就是它所说的。
@JonBentley - 您引用的链接中的问题是代码不会重载逻辑运算符，因此枚举被提升为 int，结果是 int。如果您提供自己的重载，则可以返回正确的类型。
@PeteBecker - 如果参数的整数值不是枚举值之一，则将参数设为 Options 是未定义的行为。除非您定义所有可能的组合，否则这不会发生。这对于少数选项是可行的。具有 256 个值的枚举（例如）非常笨拙。将其与仅 8 位标志进行比较。

【解决方案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 */}

【讨论】：

这更像是关于文档样式的辩论，并没有回答我的问题 - 也许更适合评论而不是答案。碰巧，我不同意——我发现将自我文档与完整的注释文档结合起来非常有用，因为它使快速阅读代码变得更加容易，并且编写 cmets 鼓励我思考目的和我的代码的组织。
另外，这不是我的实际代码——我设计这个例子是为了问我的问题。我的真实代码将提供更多上下文。这不是我关心的 cmets 的内容，而是如何让文档出现在正确的位置，所以我的示例侧重于该元素，而不是提供理想的评论内容。