在我的库中,我有很多形式的函数重载:
/// \brief Does thing.
///
/// \details The thing that is done is very special.
template<typename T>
void do_stuff(const T& t);
/// \brief Does thing repeatedly.
/// \copydetails do_stuff()
template<typename T>
void do_stuff(const T& t, std::size_t x);
一般来说,这很有效,而且非常好,但创建的效果相同 文档部分多次。我想要的是,将那些 一起发挥作用。有详细的描述和每一个 用它的简短描述注释的重载。我也不反感 到可以执行此类操作的别名或输入过滤器。
我可以想象的一种方式是:
文档结果应如下所示:
template<typename T>
void do_stuff(const T& t); (1)
template<typename T>
void do_stuff(const T& t, std::size_t x); (2)
The things that is done is very special.
(1) Does thing.
(2) Does thing repeatedly.
当然,我可以创建一个新页面并编写那种文档 手动,但它需要我重复函数声明 到页面上,然后将链接打入实际功能 文档,但这更像是一种 hack。
有没有办法轻松实现这一点?甚至提示破解它 doxygen 将不胜感激。
最佳答案
遗憾的是,Doxygen 并没有真正的机制来做到这一点。您可以获得的最接近的东西是成员组,但它们并不能满足您的需要(它们只出现在成员原型(prototype)列表中)。
在不修改 Doxygen 本身的情况下将其侵入 Doxygen,通常会涉及解析它的 XML 格式,这会带来许多问题。首先,它的 XML 格式对于做任何有用的事情来说都是糟糕(相信我;我已经尝试过了)。其次,没有用于在这些函数之间创建链接的语法。 copydetails
行类似于 C/C++ 中的 #include
;包含后不留痕迹。所以你无法知道它是什么时候真正使用的。
第三,您将丢弃 Doxygen 提供的所有其他格式。您将为您感兴趣的任何格式编写一个完整的生成器。
修改 Doxygen 本身以支持这一点将涉及许多步骤。首先,您必须添加链接命令的特殊语法。这包括修改 FuncDef
类以引用另一个与其分组的 FuncDef
。其次,您需要修改 HTML 生成器以在同一位置生成它们。那会比听起来要困难很多很多。除非 Doxygen 的内部源代码自从我上次看到它以来变得更好,否则这样做会很痛苦。
HTML 生成器对哪些链接指向哪些内容以及您要查找的内容会破坏它们有一些基本假设。请记住:您不是第一个希望从 Doxygen 获得此产品的人。然而,它还没有完成。原因之一是实现起来并不简单。老实说,我想另一个原因是 Dimitri 根本不相信这是文档应该实际做的事情。
关于c++ - 在 doxygen 中对重载进行分组,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/11860660/