如何用doxygen编写C++模板和模板元函数的文档

How to document C++ templates and template metafunctions with doxygen?

本文关键字：函数 文档 何用 编写 C++ doxygen      更新时间：2023-10-16

关于C++模板和模板元函数应该如何使用Doxygen进行文档记录，有什么指导方针吗？

例如：

/// @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记录模板参数的替代方法
  • CCD_ 3用于描述元函数

应如何记录元函数的"返回类型"？

有人对使用带有C++模板的Doxygen有什么好的建议或个人偏好吗？

将@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;
};

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

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

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

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

相关文章：