blocks|key|1176126|text|元编程似乎实现了数学。我会在doxygen文档中使用latex转义来编写描述数学公式。|type|unstyled|depth|inlineStyleRanges|entityRanges|data|1176127|entityMap^0|0^^$0|@$1|2|3|4|5|6|7|D|8|@]|9|@]|A|$]]|$1|B|3|-4|5|6|7|E|8|@]|9|@]|A|$]]]|C|$]]

The meta-programming seems to implement maths. I would write the describing mathematical formulas with latex escapes in the doxygen documentation.

blocks|key|962002|text|使用预处理器宏。这里有一个来自the+not-yet-official+Boost.XInt+library的例子(目前在Boost中排队等待审查)：|type|unstyled|depth|inlineStyleRanges|entityRanges|offset|length|data|962003|#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|code-block|syntax|javascript|962004|在需要的地方使用#defined宏名称而不是模板参数，如下所示：|style|CODE|962005|/*!+\brief+The+integer_t+class+template.

This+class+implements+the+standard+aribitrary-length+%25integer+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|962006|并将如下代码行放入like文件：|962007|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|962008|结果是Doxygen看到的不是"...“或者"other“作为模板参数，编译器就会看到真正的参数。如果在文档中描述类本身的模板参数，那么库的用户只需要在他可能查找它们的一个地方看到它们；它们将隐藏在其他任何地方。|962009|这种设计的另一个优点是，如果您需要更改模板参数列表，则只需在宏定义和实际使用更改参数的函数中进行更改。其他一切都会自动适应。|962010|entityMap|0|LINK|mutability|MUTABLE|url|http://www.boostpro.com/vault/index.php?action=downloadfile&filename=xint.zip^0|F|13|0|0|0|8|7|0|0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|14|8|@]|9|@$A|15|B|16|1|17]]|C|$]]|$1|D|3|E|5|F|7|18|8|@]|9|@]|C|$G|H]]|$1|I|3|J|5|6|7|19|8|@$A|1A|B|1B|K|L]]|9|@]|C|$]]|$1|M|3|N|5|F|7|1C|8|@]|9|@]|C|$G|H]]|$1|O|3|P|5|6|7|1D|8|@]|9|@]|C|$]]|$1|Q|3|R|5|F|7|1E|8|@]|9|@]|C|$G|H]]|$1|S|3|T|5|6|7|1F|8|@]|9|@]|C|$]]|$1|U|3|V|5|6|7|1G|8|@]|9|@]|C|$]]|$1|W|3|-4|5|6|7|1H|8|@]|9|@]|C|$]]]|X|$Y|$5|Z|10|11|C|$12|13]]]]

Use preprocessor macros. Here's an example from <a href="http://www.boostpro.com/vault/index.php?action=downloadfile&amp;filename=xint.zip" rel="noreferrer">the not-yet-official Boost.XInt library</a> (presently queued for review for inclusion in Boost):

<pre><code>#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
</code></pre>

Use the <code>#define</code>d macro names instead of the template parameters, everywhere you need them, like so:

<pre><code>/*! \brief The integer_t class template.

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

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

And put lines like these in the Doxyfile:

<pre><code>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
</code></pre>

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.

blocks|key|962043|text|以下是我对此的看法：|type|unstyled|depth|inlineStyleRanges|entityRanges|data|962044|///
///+\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... 
///+Partially+specializes+Kernel+with+meta::braket<A,B,C,D\>. 
///+If+quadrature<meta::braket<A,B,C,D\>,+Transform\>+is+true+then+enable
///+this+algorithm,+otherwise+enable+this+other+algorithm. 
///+Inherits+privately+from+template+class+Eri<Transform\> 
///+\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>+{};

///+\}|code-block|syntax|javascript|962045|不要忘记将DOXY添加到Doxygen的预处理器的预定义部分中。|962046|我通常更喜欢对代码的用户隐藏实现细节，所以我更改了Doxygen看到的内容。在这种情况下，您会发现您的所有专业化认证都在一个组下，即内核组下，而在class列表下，所有专业化认证都将被分组在一起，并且不会有一个很长且难以理解的名称。|962047|希望能有所帮助。|962048|entityMap^0|0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|O|8|@]|9|@]|A|$]]|$1|B|3|C|5|D|7|P|8|@]|9|@]|A|$E|F]]|$1|G|3|H|5|6|7|Q|8|@]|9|@]|A|$]]|$1|I|3|J|5|6|7|R|8|@]|9|@]|A|$]]|$1|K|3|L|5|6|7|S|8|@]|9|@]|A|$]]|$1|M|3|-4|5|6|7|T|8|@]|9|@]|A|$]]]|N|$]]

Here is my take on it:

<pre><code>///
/// \defgroup Kernel Kernel
///
/// \brief Kernel does this and that
/// \{

/// \brief Kernel template class brief description.
template&lt;Braket,Transform,Boolean&gt;
struct Kernel
{};

/// \brief Kernel partial template specialization brief description.
///
/// More detailed description...&lt;br&gt;
/// Partially specializes Kernel with meta::braket&lt;A,B,C,D\&gt;.&lt;br&gt;
/// If quadrature&lt;meta::braket&lt;A,B,C,D\&gt;, Transform\&gt; is true then enable
/// this algorithm, otherwise enable this other algorithm.&lt;br&gt;
/// Inherits privately from template class Eri&lt;Transform\&gt;&lt;br&gt;
/// \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\&lt;Braket,Transform,Boolean\&gt;
/// \see Eri
/// \see meta::braket
/// \see quadrature
#ifdef DOXY
// This is the documentation version
template&lt;A,B,C,D,Transform&gt;
struct Kernel&lt;Braket,Transform,Boolean&gt;
#else
// This is what gets compiled
template&lt;rysq::type A, rysq::type B, rysq::type C, rysq::type D, class Transform&gt;
struct Kernel&lt;meta::braket&lt;A,B,C,D&gt;, Transform,typename boost::enable_if&lt;quadrature&lt;meta::braket&lt;A,B,C,D&gt;, Transform&gt; &gt;::type&gt;
#endif
: Eri &lt;Transform&gt; {};

/// \}
</code></pre>

Don't forget to add DOXY in the PREDEFINED section of Doxygen's preprocessor.

I usually prefer to hide implementation details from the user of my code, so I change what Doxygen sees.
In this case, you will find all your specializations under one group, the Kernel group, and under the class list, all specializations will be grouped together and won't have a very long and un-comprehensible name.

Hope it helps.

blocks|key|1176323|text|我不喜欢带有附加宏/代码的解决方案，比如the+swine。|type|unstyled|depth|inlineStyleRanges|entityRanges|offset|length|data|1176324|这是我的解决方案，基于对Doxygen生成的HTML页面的后处理。|1176325|它是一个在Linux下工作的python脚本。它禁止模板类和结构引用页面中的所有"<...>“，以及它们的”所有成员页面列表“中的所有”成员“。|1176326|每种文档化方法之前的侵入性越来越小的"template<...>“仍然存在。|1176327|使用"html/“目录(生成文档的位置)作为参数运行脚本。|1176328|#!/usr/bin/python

import+subprocess
import+sys
import+re

def+processFile(+fileName):

++f+=+open(+fileName,+'r')

++content+=+f.read();

++f.close();

++regex+=+re.compile(+"(&lt;.*&gt;).*(Template+Reference%7CMember+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)|code-block|syntax|javascript|1176329|entityMap|0|LINK|mutability|MUTABLE|url|https://stackoverflow.com/users/1140976/the-swine^0|K|9|0|0|0|0|0|0|0^^$0|@$1|2|3|4|5|6|7|Y|8|@]|9|@$A|Z|B|10|1|11]]|C|$]]|$1|D|3|E|5|6|7|12|8|@]|9|@]|C|$]]|$1|F|3|G|5|6|7|13|8|@]|9|@]|C|$]]|$1|H|3|I|5|6|7|14|8|@]|9|@]|C|$]]|$1|J|3|K|5|6|7|15|8|@]|9|@]|C|$]]|$1|L|3|M|5|N|7|16|8|@]|9|@]|C|$O|P]]|$1|Q|3|-4|5|6|7|17|8|@]|9|@]|C|$]]]|R|$S|$5|T|U|V|C|$W|X]]]]

I don't like the solution with additional macros/code, like <a href="https://stackoverflow.com/users/1140976/the-swine">the swine</a>.

Here is my solution based on a post-processing of the HTML pages generated by Doxygen.

It is a python script which works under Linux. It suppresses all the "&lt;...>" in Template Classes and Structures Reference pages, and also in their "List of all members pages".

The little and less invasive "template&lt;...>" before each documented method remains.

Run the script with the "html/" directory (where the documentation was generated) as argument.

<pre><code>#!/usr/bin/python

import subprocess
import sys
import re

def processFile( fileName):

 f = open( fileName, 'r')

 content = f.read();

 f.close();

 regex = re.compile( "(&amp;lt;.*&amp;gt;).*(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)
</code></pre>

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

<pre><code> template&lt;rysq::type A, rysq::type B, rysq::type C, rysq::type D, class Transform&gt;
 struct Kernel&lt;meta::braket&lt;A,B,C,D&gt;, Transform,
 typename boost::enable_if&lt;
 quadrature&lt;meta::braket&lt;A,B,C,D&gt;, Transform&gt; &gt;::type&gt;
 : Eri &lt;Transform&gt; {
</code></pre>

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

C++ meta-programming doxygen documentation

编译器

Kernel

Linux

我正在记录一些大量使用元编程的代码，例如： template<rysq::type A, rysq::type B, rysq::type C, rysq::type D, class Transform> struct Kernel<meta::braket<A,B,C,D>, Transform, ...

问C++元编程doxygen文档
EN

社区

活动

资源

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问C++元编程doxygen文档EN

社区

活动

资源

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问C++元编程doxygen文档
EN