用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 */}
};

如何向用戶指示如何使用bar功能的options參數？ 參數的類型為int，而不是選項，因此參數與枚舉之間沒有直接鏈接。 如果參數的類型為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 */}