doxygenを使ってC++テンプレートとテンプレートメタ関数を文書化するには？

Question

C++テンプレートとテンプレートメタ関数をDoxygenで文書化する方法に関するガイドラインはありますか？例えば

：テンプレートパラメータを文書化するために使用さ

• @tparam：

  /// @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; 
  }; 
  

  これまでのところ、私は次の提案を見てきました。

• @argテンプレートパラメータを文書化する別の方法です。
• @briefを使用してメタ機能を記述します。メタ関数のための「が返さタイプは」文書化する必要がありますどのよう

？

誰もがC++テンプレートを使用してDoxygenのを使用するための任意の良い提案や個人的な好みを持っていますか？

Answer 1

私はそれはそれは、もともとオブジェクト指向のパラダイムのために設計されており、metaprogramingれていなかったので、文書の高度なテンプレートは、doxygenを有する構築物の可能な使用ではないと思います。例として、GNU STL（libstdC++）はdoxygenを使用しますが、STLでメタプログラミングを文書化するのはpoor jobです。一方

、ブーストは、独自のツールを使用しています：QuickBookはターンでHTML/PDFを生成BoostBookマークアップ（DocBookの拡張子）を生成するために、スタンドアロンのテキストファイルとdoxygenの文書化されたソースを使用しています。 resultはlibstdC++よりも有益ですが、明らかに開発者からもう少し作業が必要です。ブーストドキュメント以来

は間違いなくあなたはそれがdoxygenのを補完し、特に以来、そのルートを行くことができるmetaprogramingのための最高の一つである - あなたは、既存のマークアップを再利用することができます。

それは正確にあなたの質問に答えていませんが、最近の打ち鳴らすdevelopmentsに興味があるかもしれません。 --with-extra-options=-Wdocumentationでclangをビルドすると、意味的にあなたのコードとあなたのdoxygenマークアップがチェックされ、ドキュメントの警告が生成されます。ドキュメント/コードの同期を保つようにします。

Answer 2

は、関数の引数のための@argを@tparamテンプレート引数を使用します。戻り値は@returnです。ここには帰りはありません。ちょうどtypedefsがあります。

ところで、サンプルコードはメタ機能のようには見えません。メタ機能は、C++がもともと意図していなかったこと（例えば反射）を行うためにSFINAEを利用する毛深い獣です。 generate_callback_mapは、テンプレートtypedefのスタンドアロンのC++ 03のように見えます。あなたが不足している何

はあなたのtypedefと、このテンプレートを使用する方法についてのマニュアルのドキュメントです。

/// @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; 
};