歸檔枚舉標誌相似

我剛剛加入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，因此參數和枚舉之間沒有直接關聯。如果參數的類型爲Options，那麼文檔將鏈接到枚舉的描述，這是我想要的行爲。

來源

2012-11-29 JBentley

所以使參數類型Options。你可以寫重載運算符返回Options處理&和|和所需的任何其他邏輯運算符。

來源

2012-11-29 21:42:48

我遇到過建議您不應該對包含位標記的變量使用枚舉類型，例如， [鏈接]（http://stackoverflow.com/a/1448404/1227469） – JBentley

你不能這樣做，除非枚舉枚舉所有可能的位組合。 Jon Bentley的枚舉只是命名個別選項，並不是所有可能的方式選項都可以結合使用。 –

@DavidHammen - 當然可以。普通枚舉的基礎類型足夠大，可以容納定義值的所有可能組合，並且所有值的組合對於枚舉都是有效的。 7.2 [dcl.enum]/7在這裏引用太長，但這就是它所說的。 –

文檔化一個名爲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 */}

來源

2012-11-29 22:10:51

這更像是關於文檔樣式的爭論，並沒有回答我的問題 - 可能更適合評論而不是回答。碰巧，我不同意 - 我發現它非常有用，它將自我文檔和完整的註釋文檔結合起來，因爲它可以讓代碼更快地閱讀代碼，並且寫出評論鼓勵我去思考這個目的並組織我的代碼。 – JBentley

另外，這不是我的實際代碼 - 我爲了問我的問題而設計了這個例子。我真正的代碼將提供更多的上下文。這不是我所關注的評論內容，而是如何讓文檔出現在正確的位置，所以我的示例關注的是這個元素，而不是提供理想的評論內容。 – JBentley

歸檔枚舉標誌相似

回答

相關問題