c++ - 如何使用 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;
};