如何使用 doxygen 记录 C++ 模板和模板元函数？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/13359217/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How to document C++ templates and template metafunctions with doxygen?
提问by mark
Are there any guidelines on how C++ templates and template meta-functions should be documented with Doxygen?
是否有关于如何使用 Doxygen 记录 C++ 模板和模板元函数的指南？
For example:
例如：
/// @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;
};
So far I have seen the following suggestions:
到目前为止，我看到了以下建议：
@tparamused to document template parameters.@argalternative way of documenting template parameters.@briefused to describe the metafunction.
@tparam用于记录模板参数。@arg记录模板参数的替代方法。@brief用于描述元功能。
How should the 'returned type' for the metafunction be documented?
应该如何记录元函数的“返回类型”？
Does anyone have any good suggestions or personal preferences for using Doxygen with C++ templates?
对于将 Doxygen 与 C++ 模板一起使用，有人有什么好的建议或个人偏好吗？
采纳答案by Antoine
I don't think it is possible use document advanced template constructs with doxygen since it was originally designed for the object oriented paradigm and not metaprograming. As an illustration,GNU STL (libstdc++) uses doxygen but does a poor jobof documenting metaprograming in the STL.
我认为不可能将文档高级模板构造与 doxygen 一起使用，因为它最初是为面向对象的范式而不是元编程设计的。例如，GNU STL (libstdc++) 使用了 doxygen，但在记录 STL 中的元编程方面做得很差。
On the other hand, boost uses its own tools: QuickBookuses standalone text files and doxygen documented source to generate BoostBookmarkup (extension of DocBook) which in turns generates html/pdf. The resultis more informative than for libstdc++ but obviously involves a little more work from the dev.
另一方面，boost 使用自己的工具：QuickBook使用独立的文本文件和 doxygen 文档源来生成BoostBook标记（DocBook 的扩展），然后生成 html/pdf。该结果是比的libstdc更多的信息++但显然涉及从开发多一点的工作。
Since boost documentation is arguably one of the best for metaprograming you could go that route, especially since it complements doxygen - you can reuse your existing markup.
由于 boost 文档可以说是元编程的最佳文档之一，因此您可以走这条路，特别是因为它补充了 doxygen - 您可以重用现有的标记。
Although it does not exactly answer your question, you might be interested in recent clang developments. When building clang with --with-extra-options=-Wdocumentationit semantically checks your doxygen markup with your code and generates documentation warnings. Forces you to keep docs/code synchronized.
虽然它不能完全回答您的问题，但您可能对最近的 clang发展感兴趣。使用--with-extra-options=-Wdocumentation它构建 clang 时，会在语义上检查您的 doxygen 标记与您的代码并生成文档警告。强制您保持文档/代码同步。
回答by David Hammen
Use @tparamfor template arguments, @argfor function arguments. For return values, @return. There is no return here. There are just typedefs.
使用@tparam模板参数，@arg函数参数。对于返回值，@return. 这里没有回头路。只有typedefs。
BTW, your sample code doesn't look like a metafunction. Metafunctions are hairy beasts that take advantage of SFINAE to do something that C++ wasn't originally intended to do (e.g., reflection). Your generate_callback_mapjust looks like a C++03 stand-in for a template typedef.
顺便说一句，您的示例代码看起来不像元函数。元函数是毛茸茸的野兽，它们利用 SFINAE 来做一些 C++ 原本不打算做的事情（例如，反射）。您generate_callback_map只是看起来像模板 typedef 的 C++03 替代品。
What you are missing is documentation on your typedefs and documentation on how to use this template.
您缺少的是有关您的 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;
};
