68

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

例えば:

/// @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メタ関数を説明するために使用されます。

メタ関数の「返されたタイプ」はどのように文書化する必要がありますか?

C ++テンプレートでDoxygenを使用するための良い提案や個人的な好みはありますか?

4

2 に答える 2

67

@tparamテンプレートの引数、@arg関数の引数に使用します。戻り値については、@return. ここに戻ることはありません。sだけがありますtypedef

ところで、サンプル コードはメタ関数のようには見えません。メタ関数は、SFINAE を利用して、C++ が本来意図していなかったこと (リフレクションなど) を実行する毛むくじゃらの獣です。テンプレートtypedefgenerate_callback_mapの 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;
};
于 2012-11-13T11:20:53.850 に答える
23

もともとはオブジェクト指向パラダイム用に設計されており、メタプログラミングではないため、doxygenでドキュメントの高度なテンプレート構造を使用することは不可能だと思います。例として、GNU STL(libstdc ++)はdoxygenを使用しますが、STLでのメタプログラミングの文書化には不十分です。

一方、boostは独自のツールを使用します。QuickBookはスタンドアロンのテキストファイルとdoxygenで文書化されたソースを使用して、BoostBookマークアップ(DocBookの拡張)を生成し、それがhtml/pdfを生成します。結果はlibstdc++よりも有益ですが、明らかに開発者からの作業が少し多くなります。

ブーストドキュメンテーションは間違いなくメタプログラミングに最適なものの1つであるため、特にdoxygenを補完するため、そのルートに進むことができます。既存のマークアップを再利用できます。

それはあなたの質問に正確に答えるものではありませんが、あなたは最近のclangの開発に興味があるかもしれません。それを使用してclangを構築する--with-extra-options=-Wdocumentationと、コードを使用してdoxygenマークアップをセマンティックにチェックし、ドキュメントの警告を生成します。ドキュメント/コードの同期を維持するように強制します。

于 2012-11-29T14:21:58.180 に答える