模板或函数参数作为 doxygen 中的实现细节？答案

【问题标题】：Template or function arguments as implementation details in doxygen?模板或函数参数作为 doxygen 中的实现细节？
【发布时间】：2012-09-15 02:41:40
【问题描述】：

在doxygen中有没有通用的方式来指定函数参数的一些C++模板参数是实现细节，不应该由用户指定？

例如，在元编程技术中用作递归级别计数器的模板参数或函数中的 SFINAE 参数？

例如：

/// \brief Do something
/// \tparam MyFlag A flag...
/// \tparam Limit Recursion limit
/// \tparam Current Recursion level counter. SHOULD NOT BE EXPLICITELY SPECIFIED !!!
template<bool MyFlag, unsigned int Limit, unsigned int Current = 0> myFunction();

是否有任何 doxygen 标准化选项等效于“不应该明确指定！！！” ?

【问题讨论】：

标签： c++ parameters doxygen

【解决方案1】：

在我看来，整个模板是不同接口的实现细节：

template<bool MyFlag, unsigned int Limit, unsigned int Current = 0> myFunctionImpl();

template<bool MyFlag, unsigned int Limit> myFunction() {
   myFunctionImpl<MyFlag, Limit, 0>();
}

现在记录变得更容易了：myFunction()（及其所有参数）是接口的一部分，不包括迭代计数器。 myFunctionImpl() 是该接口的实现，根本不需要文档化（或者只需要最少的注释说明它是一个实现细节，用户代码不应依赖它或直接使用它）。如果需要，您可以将实现包含在 #ifdef 块中，以便 doxygen 预处理器将其删除，并且不会出现在生成的文档中。

【讨论】：

【解决方案2】：

传达不应指定参数的一种选择是将其隐藏在文档中。例如，您可以有条件地编译出内部参数：

/// \brief Do something
/// \tparam MyFlag A flag...
/// \tparam Limit Recursion limit
template<bool MyFlag, unsigned int Limit
#if !defined(DOXYGEN)
        , unsigned int Current = 0
#endif
> myFunction();

这将阻止它们出现在文档中，但它们仍可用于实现。

【讨论】：