如何使用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

使用@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;
};

Answer 2

我不认为有可能使用带有doxygen的文档高级模板构造,因为它最初是为面向对象的范例设计的而不是元编程.作为一个例子,GNU STL(libstdc ++)使用doxygen,但在STL中记录元编程的工作很差.

另一方面,boost使用自己的工具:QuickBook使用独立的文本文件和doxygen文档源生成BoostBook标记(DocBook的扩展),然后生成html/pdf.该结果是比的libstdc更多的信息++但显然涉及从开发多一点的工作.

由于boost文档可以说是最好的元编程之一,你可以走这条路,特别是因为它补充了doxygen - 你可以重用你现有的标记.

虽然它没有完全回答你的问题,但你可能会对最近的铿锵发展感兴趣.使用--with-extra-options=-Wdocumentation它构建clang 语义时会使用您的代码检查doxygen标记并生成文档警告.强制您保持文档/代码同步.