在doxygen中对重载进行分组

Question

在doxygen中对重载进行分组

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中的提示也将不胜感激。

- pmr

2个回答

14

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

它产生以下输出： enter image description here

希望这能帮助到您。

- nogard

据我所知，这仅适用于成员组。我应该提到我需要这个在自由函数中运行。 - pmr

@pmr 不，它同样适用于命名空间内的函数。但是我从未尝试过没有命名空间的自由函数，因为我没有这样的函数。 - nogard

一个不错的开始。那么这本质上与每个重载使用单独组的解决方案是相同的吗？ - pmr

不确定我是否正确理解了你的问题，但这是一个针对所有重载的单独分组，而不是“每个重载一个分组”。然后，您可以在该组中为每个重载编写单独的文档。 - nogard

2

成员组只在短描述功能列表中真正分组。它们不会出现在长格式文档中。因此，这并没有太大帮助。 - Nicol Bolas

显示剩余2条评论

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Nicol Bolas · Accepted Answer

遗憾的是，Doxygen实际上没有这样的机制。你可以使用最接近你需求的成员组，但它们无法做到你所需要的（它们仅出现在成员原型列表中）。

如果不修改Doxygen本身，将其嵌入其中通常涉及解析其XML格式，这会带来一些问题。首先，它的XML格式对于做任何有用的事情都非常糟糕（相信我，我试过了）。其次，不存在创建这些函数之间链接的语法。 copydetails 行就像 C/C++ 中的 #include 一样；在包含之后不留痕迹，因此您无法确定它何时被使用。

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

修改Doxygen本身以支持此功能需要多个步骤。首先，您需要添加特殊的语法来链接这些命令。这包括修改 FuncDef 类以引用它所分组的另一个 FuncDef。其次，您需要修改HTML生成器以在同一位置生成它们。除非Doxygen的内部源代码自我更新得比我上次看到的要好得多，否则这会很麻烦。

HTML生成器对链接的内容有一些基本假设，而你需要的东西会打破它们。记住：你不是第一个想从Doxygen中获得这个功能的人。然而，它还没有被实现。其中一个原因是它不太容易实现。不过，老实说，我想另一个原因可能是Dimitri根本不相信文档应该真正做到这一点。