web-dev-qa-db-ja.com

doxygenでC ++テンプレートとテンプレートメタ関数を文書化する方法は？

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++テンプレートで使用するための良い提案や個人的な好みはありますか？

c++templatesdoxygen
51
mark

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

一方、boostは独自のツールを使用します： QuickBook は、スタンドアロンテキストファイルとdoxygenのドキュメント化されたソースを使用して BoostBookを生成します マークアップ（ DocBook の拡張）これにより、html/pdfが生成されます。 result はlibstdc ++よりも有益ですが、明らかにdevからのもう少しの作業が含まれます。

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

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

19
Antoine

つかいます @tparamテンプレート引数の場合、@arg関数の引数。戻り値の場合、@return。ここには返品はありません。 typedefsだけがあります。

ところで、サンプルコードはメタ関数のようには見えません。メタファンクションは、SFINAEを利用してC++が本来意図していないこと（リフレクションなど）を行う毛深い獣です。きみの 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;
};
44
David Hammen