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。这里没有回报。只有typedef s。

顺便说一下，您的示例代码看起来不像元函数。元功能是毛茸茸的野兽，利用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中记录元编程poor job。

另一方面，boost使用自己的工具：QuickBook使用独立的文本文件和doxygen文档源生成BoostBook标记（DocBook的扩展名），然后生成html / PDF格式。 result比libstdc ++更有用，但显然需要开发人员的更多工作。

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

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

如何使用doxygen记录C ++模板和模板元函数？

2 个答案: