在doxygen中对重载进行分组

Question

在我的库中,我有很多函数重载的形式:

/// \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.

当然我可以创建一个新页面并手动编写这种文档,但是它需要我在页面上重复函数声明,然后将链接打到实际的函数文档中,但这比其他任何东西都要糟糕.

有没有办法轻松实现这一目标？甚至暗示将其破解为doxygen也会受到赞赏.

Answer 1

可悲的是,Doxygen实际上并没有这样做的机制.您可以获得的最接近的成员是成员组,但那些不能满足您的需求(它们只出现在成员原型列表中).

在不修改Doxygen本身的情况下将其黑客入Doxygen通常会涉及解析它的XML格式,这会带来许多问题.首先,它的XML格式对于做任何有用的事情都很糟糕(相信我;我已经尝试过了).其次,没有用于在这些函数之间创建链接的语法.这copydetails条线就像#include在C/C++中; 包含后它没有留下任何痕迹.所以你无法确定它何时被实际使用.

第三,你将丢弃Doxygen提供的所有其他格式.你会为你感兴趣的任何格式编写一个完整的生成器.

修改Doxygen本身以支持这将涉及许多步骤.首先,您必须添加链接命令的特殊语法.这包括修改FuncDef类以引用FuncDef与其组合的另一个类.其次,您需要修改HTML生成器以在同一位置生成它们.那个比听起来要困难得多.除非Doxygen的内部源代码自从我上次看到它以后变得更好,否则这将是一件非常痛苦的事情.

HTML生成器有一些关于什么链接的基本假设,以及你正在寻找什么打破了它们.请记住:你不是第一个想要Doxygen的人.然而,它还没有完成.其中一个原因是实施它并非易事.老实说,我想另一个原因是Dimitri根本不相信这是文档应该实际做的事情.

Answer 2

您可以使用@name标记来实现类似的功能.看看这个例子,这很容易.

    /**
     * @name Appends data to the container.
     *
     * @param tag Name of the data entry
     * @param value Data value
     */
    //@{
    /**
     * @brief Documentation for this overload
     */
    void append(const std::string & tag, bool value);

    /**
     * @brief Documentation for this overload
     */
    void append(const std::string & tag, int8_t value);

    void append(const std::string & tag, int16_t value);
    void append(const std::string & tag, int32_t value);
    //@}

它产生以下输出:

我希望这个能帮上忙