我正在记录一些大量使用元编程的代码,例如:
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记录此类构造的好方法是什么?
发布于 2010-08-15 13:19:55
使用预处理器宏。这里有一个来自the not-yet-official Boost.XInt library的例子(目前在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宏名称而不是模板参数,如下所示:
/*! \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
并将如下代码行放入like文件:
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“作为模板参数,编译器就会看到真正的参数。如果在文档中描述类本身的模板参数,那么库的用户只需要在他可能查找它们的一个地方看到它们;它们将隐藏在其他任何地方。
这种设计的另一个优点是,如果您需要更改模板参数列表,则只需在宏定义和实际使用更改参数的函数中进行更改。其他一切都会自动适应。
发布于 2010-08-21 02:59:22
以下是我对此的看法:
///
/// \defgroup Kernel Kernel
///
/// \brief Kernel does this and that
/// \{
/// \brief Kernel template class brief description.
template<Braket,Transform,Boolean>
struct Kernel
{};
/// \brief Kernel partial template specialization brief description.
///
/// More detailed description...<br>
/// Partially specializes Kernel with meta::braket<A,B,C,D\>.<br>
/// If quadrature<meta::braket<A,B,C,D\>, Transform\> is true then enable
/// this algorithm, otherwise enable this other algorithm.<br>
/// Inherits privately from template class Eri<Transform\><br>
/// \tparam A template parameter A of type rysq::type, documentation and concepts
/// \tparam B template parameter B of type rysq::type, documentation and concepts
/// \tparam C template parameter C of type rysq::type, documentation and concepts
/// \tparam D template parameter D of type rysq::type, documentation and concepts
/// \tparam Transform template parameter class Transform documentation and concepts
/// \see Kernel\<Braket,Transform,Boolean\>
/// \see Eri
/// \see meta::braket
/// \see quadrature
#ifdef DOXY
// This is the documentation version
template<A,B,C,D,Transform>
struct Kernel<Braket,Transform,Boolean>
#else
// This is what gets compiled
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>
#endif
: Eri <Transform> {};
/// \}
不要忘记将DOXY添加到Doxygen的预处理器的预定义部分中。
我通常更喜欢对代码的用户隐藏实现细节,所以我更改了Doxygen看到的内容。在这种情况下,您会发现您的所有专业化认证都在一个组下,即内核组下,而在class列表下,所有专业化认证都将被分组在一起,并且不会有一个很长且难以理解的名称。
希望能有所帮助。
发布于 2013-12-23 23:08:58
我不喜欢带有附加宏/代码的解决方案,比如the swine。
这是我的解决方案,基于对Doxygen生成的HTML页面的后处理。
它是一个在Linux下工作的python脚本。它禁止模板类和结构引用页面中的所有"<...>“,以及它们的”所有成员页面列表“中的所有”成员“。
每种文档化方法之前的侵入性越来越小的"template<...>“仍然存在。
使用"html/“目录(生成文档的位置)作为参数运行脚本。
#!/usr/bin/python
import subprocess
import sys
import re
def processFile( fileName):
f = open( fileName, 'r')
content = f.read();
f.close();
regex = re.compile( "(<.*>).*(Template Reference|Member List)")
match = re.search( regex, content)
if not match:
return
toRemove = match.group(1)
regex = re.compile(toRemove)
content = re.sub( regex, "", content)
f = open( fileName, 'w')
f.write( content)
f.close()
path = sys.argv[1]
finder = subprocess.Popen(["find", path, "-name", "class*.html", "-o", "-name", "struct*.html"], stdout = subprocess.PIPE)
(files, junk) = finder.communicate()
files = files.splitlines()
print files
for fname in files:
if fname == "":
continue
processFile(fname)
https://stackoverflow.com/questions/3435225
复制相似问题