C ++元编程doxygen文档 [英] C++ meta-programming doxygen documentation

问题描述

我记录了大量使用元编程的代码，例如：

I am documenting some code which uses meta-programming heavily, for example:

 template<rysq::type A, rysq::type B, rysq::type C, rysq::type D, class Transform>
 struct Kernel<meta::braket<A,B,C,D>, Transform,
               typename boost::enable_if<
                   quadrature<meta::braket<A,B,C,D>, Transform> >::type>
 : Eri <Transform> {

什么是使用doxygen记录此类结构的好方法？

what is a good way to document such construct using doxygen?

推荐答案

使用预处理器宏。以下是尚未升级的Boost.XInt库的示例（目前排队等待审查是否包含在Boost中）：

Use preprocessor macros. Here's an example from the not-yet-official Boost.XInt library (presently queued for review for inclusion in Boost):

#ifdef BOOST_XINT_DOXYGEN_IGNORE
    // The documentation should see a simplified version of the template
    // parameters.
    #define BOOST_XINT_INITIAL_APARAMS ...
    #define BOOST_XINT_CLASS_APARAMS ...
    #define BOOST_XINT_CLASS_BPARAMS other
    #define BOOST_XINT_APARAMS ...
    #define BOOST_XINT_BPARAMS other
#else
    #define BOOST_XINT_INITIAL_APARAMS \
        class A0 = parameter::void_, \
        class A1 = parameter::void_, \
        class A2 = parameter::void_, \
        class A3 = parameter::void_, \
        class A4 = parameter::void_, \
        class A5 = parameter::void_
    #define BOOST_XINT_CLASS_APARAMS class A0, class A1, class A2, class A3, \
        class A4, class A5
    #define BOOST_XINT_APARAMS A0, A1, A2, A3, A4, A5
    #define BOOST_XINT_CLASS_BPARAMS class B0, class B1, class B2, class B3, \
        class B4, class B5
    #define BOOST_XINT_BPARAMS B0, B1, B2, B3, B4, B5
#endif

使用 #define d宏名称而不是模板参数你需要他们，像这样：

Use the #defined macro names instead of the template parameters, everywhere you need them, like so:

/*! \brief The integer_t class template.

This class implements the standard aribitrary-length %integer type.

[...lots more documentation omitted...]
*/
template<BOOST_XINT_INITIAL_APARAMS>
class integer_t: virtual public detail::integer_t_data<BOOST_XINT_APARAMS>,
    public detail::nan_functions<detail::integer_t_data<BOOST_XINT_APARAMS>::
    NothrowType::value, // ...lots more base classes omitted...
{
    // ...etcetera

将Doxyfile中的这些行放在Doxyfile中：

And put lines like these in the Doxyfile:

PREDEFINED             = BOOST_XINT_DOXYGEN_IGNORE

EXPAND_AS_DEFINED      = BOOST_XINT_INITIAL_APARAMS \
                         BOOST_XINT_CLASS_APARAMS \
                         BOOST_XINT_CLASS_BPARAMS \
                         BOOST_XINT_APARAMS \
                         BOOST_XINT_BPARAMS

结果是Doxygen为模板参数看到...或other，编译器看到真实的。如果你在类本身的文档中描述模板参数，那么库的用户只需要在他可能寻找它们的一个地方看到它们;

The result is that Doxygen sees either "..." or "other" for the template parameters, and the compiler sees the real ones. If you describe the template parameters in the documentation for the class itself, then the user of the library will only need to see them in the one place that he's likely to look for them; they'll be hidden everywhere else.

作为这个设计的额外优点，如果你需要更改模板参数列表，你只需要更改它们在宏定义和实际使用更改的参数的函数。一切都会自动适应。

As an additional advantage to this design, if you ever need to make changes to the template parameter lists, you only need to change them in the macro definitions and the functions that actually use the changed parameters. Everything else will adapt automatically.

这篇关于C ++元编程doxygen文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！