如何用doxygen編寫C++模板和模板元函數？

Question

關於如何使用Doxygen記錄C++模板和模板元函數有任何指導原則嗎？

例如：

/// @brief metafunction for generation of a map of message types to 
/// their associated callbacks. 
/// @tparam Seq the list of message types 
template< class Seq > 
struct generate_callback_map 
{ 
    typedef typename mpl::transform< Seq 
            , build_type_signature_pair<mpl::_1> 
            >::type vector_pair_type; 
    typedef typename fusion::result_of::as_map<vector_pair_type>::type type; 
}; 

到目前爲止，我已經看到了以下的建議：

• @tparam用於文檔模板參​​數。
• @arg記錄模板參數的備選方法。
• @brief用於描述元函數。

應如何記錄元功能的「返回類型」？

有沒有人有任何好的建議或個人喜好使用Doxygen與C + +模板？

Answer 1

我不認爲這是可能使用的文檔模板，先進與doxygen的構造，因爲它最初被設計爲面向對象的範例，而不是metaprograming。作爲例子，GNU STL（libstdC++）使用doxygen，但在STL中記錄了元編程的poor job。

在另一方面，增強使用自己的工具：QuickBook使用獨立的文本文件和記錄doxygen的發生源BoostBook標記（的DocBook擴展），其輪流生成HTML/PDF文件。 result比libstdC++更具信息性，但顯然涉及開發人員更多的工作。

由於boost文檔可以說是元編程的最佳選擇之一，所以您可以走這條路線，特別是因爲它補充了doxygen - 您可以重複使用現有的標記。

雖然它不完全回答你的問題，但你可能會對最近的叮噹developments感興趣。當用--with-extra-options=-Wdocumentation構建鐺聲時，它會用您的代碼語義檢查您的doxygen標記並生成文檔警告。強制您保持文檔/代碼同步。

Answer 2

使用@tparam模板參數，@arg函數參數。對於返回值，@return。這裏沒有回報。只有typedef s。

順便說一句，你的示例代碼看起來不像一個元函數。元函數是毛茸茸的野獸，它利用SFINAE來完成C++本來不打算實現的內容（例如反射）。您的generate_callback_map只是用於模板typedef的C++ 03替身。

你缺少的是關於你的typedefs的文檔和關於如何使用這個模板的文檔。

/// @brief metafunction for generation of a map of message types to 
/// their associated callbacks. 
/// @details 
/// Usage: Use <tt>generate_callback_map<Type>::type</tt> to ... 
/// @tparam Seq the list of message types 
/// 
template< class Seq > 
struct generate_callback_map 
{ 
    /// @brief It's a good idea to document all of your typedefs. 
    typedef typename mpl::transform< Seq 
           , build_type_signature_pair<mpl::_1> 
           >::type vector_pair_type; 

    /// @brief This is why generate_callback_map exists. Document it! 
    typedef typename fusion::result_of::as_map<vector_pair_type>::type type; 
};