在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行与C / C ++中的#include类似;包含后它没有留下任何痕迹。所以你无法确定它何时被实际使用。

第三，你将丢弃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);
    //@}

它产生以下输出：

我希望这会有所帮助