68

是否有关于如何使用 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++ 模板一起使用有什么好的建议或个人偏好吗？

4

2 回答 2

67

用于@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;
};
于 2012-11-13T11:20:53.850 回答
23

我认为不可能将文档高级模板结构与 doxygen 一起使用，因为它最初是为面向对象的范例而不是元编程设计的。举例来说，GNU STL (libstdc++) 使用 doxygen，但在记录 STL 中的元编程方面做得很差。

另一方面，boost 使用自己的工具：QuickBook使用独立的文本文件和 doxygen 文档源来生成BoostBook标记（DocBook的扩展），进而生成 html/pdf。结果比 libstdc++ 提供的信息更多，但显然需要开发人员做更多的工作。

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

尽管它不能完全回答您的问题，但您可能对最近的 clang发展感兴趣。使用--with-extra-options=-Wdocumentation它构建 clang 时，会在语义上使用代码检查 doxygen 标记并生成文档警告。强制您保持文档/代码同步。

于 2012-11-29T14:21:58.180 回答