15

在我的库中，我有很多形式的函数重载：

/// \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 的提示也会受到赞赏。

4

2 回答 2

15

可悲的是，Doxygen 并没有真正的机制来做到这一点。您可以获得的最接近的东西是成员组，但它们并不能满足您的需要（它们只出现在成员原型列表中）。

在不修改 Doxygen 本身的情况下将其侵入 Doxygen，通常会涉及解析它的 XML 格式，这会带来许多问题。首先，它的 XML 格式不适合做任何有用的事情（相信我；我已经尝试过了）。其次，没有用于在这些函数之间创建链接的语法。该copydetails行就像#include在 C/C++ 中一样；包含后不留痕迹。因此，您无法确定它何时实际使用。

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

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

HTML 生成器有一些关于什么链接到什么的基本假设，以及您正在寻找的内容会破坏它们。请记住：您不是第一个希望从 Doxygen 获得此产品的人。然而，它还没有完成。原因之一是实施起来并不简单。老实说，我想另一个原因是 Dimitri 根本不相信这是文档实际上应该做的事情。

于 2012-08-14T12:58:20.343 回答
12

您可以使用@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);
    //@}

它产生以下输出：在此处输入图像描述

我希望这个能帮上忙

于 2012-08-20T09:13:18.280 回答