doxygen中的分组重载 [英] Grouping overloads in doxygen

问题描述

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

  /// \brief 
 /// 
 /// \details所做的事情是非常特别的。 
 template< typename T> 
 void do_stuff（const T& t）; 
 
 /// \brief不断重复。 
 /// \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）
 
所做的事情是非常特别的。 
 
（1）做事情。 
 
（2）多次重复。 
  

当然，我可以创建一个新页面并用手写这种文档
，但它需要我重复的函数声明
到页面上，然后打印链接到实际的函数
文档，但这是一个黑客比任何其他。

有没有办法轻松实现这一点？不幸的是，Doxygen并没有真正的机制，因为它没有一个机制，去做这个。你可以得到的最接近的成员是成员组，但那些不做你需要的（他们只出现在成员原型列表中）。

将它编入Doxygen ，没有修改Doxygen本身，通常会涉及解析它的XML格式，这提出了一些问题。首先，它的XML格式是可怕的做任何有用的（相信我;我试过）。第二，没有用于在这些函数之间创建链接的语法。 copydetails 行像C / C ++中的 #include 它在包含后不留下痕迹。所以你不能告诉它什么时候被实际使用。

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

修改Doxygen本身以支持此操作将涉及多个步骤。首先，你必须添加链接命令的特殊语法。这包括修改 FuncDef 类以引用另一个 FuncDef ，它与它分组。其次，您需要修改HTML生成器以在相同的位置生成它们。那一个将是一个比你听起来更难的很多。除非Doxygen的内部源代码自上次看到它以来已经有了很多好处，这将是一个很大的痛苦。

HTML生成器有一些基本的假设，到什么，和你正在寻找打破他们。并记住：你不是第一个人谁想要这个从Doxygen。然而，它还没有完成。其中一个原因是，它的实现是不平凡的。虽然老实说，我想另一个原因是，Dimitri根本不相信这是文档应该是真正做的。

In my library I have a lot of function overloads of the form:

/// \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);

This, in general, works and is quite nice but creates the same documentation section multiple times. What I want is, to group those functions together. Have on detail description and each of the overloads annotated with it's brief description. I'm also not averse to aliases that could do something like this or input filters.

One way I could imagine this would be:

The documentation result should look like this:

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.

Of course I can create a new page and write that kind of documentation by hand, but it would require me to repeat the function declarations onto the page and then punch links into the actual function documentation, but that is more a hack than anything else.

Is there a way to achieve this easily? Even hints to hack it into doxygen would be appreciated.

解决方案

Sadly, Doxygen doesn't really have a mechanism to do this. The closest thing you could get are member groups, but those don't do what you need (they only appear in the list of member prototypes).

Hacking it into Doxygen, without modifying Doxygen itself, would generally involve parsing it's XML format, which presents a number of problems. First, its XML format is terrible for doing anything useful (believe me; I've tried). Second, there is no syntax for creating a linkage between these functions. The copydetails line is like #include in C/C++; it leaves no traces after the inclusion. So you can't tell when it was actually used.

Third, you'd be throwing away all of the other formatting that Doxygen provides. You would be writing a full generator for whatever format you're interested in.

Modifying Doxygen itself to support this will involve a number of steps. First, you have to add special grammar that links the commands. This includes modifying the FuncDef class to have a reference to another FuncDef that it is grouped with. Second, you need to modify the HTML generator to generate them in the same place. That one is going to be a lot harder than it sounds. Unless Doxygen's internal source code has gotten a lot better since I last saw it, it will be a significant pain to do.

The HTML generator has some basic assumptions about what links to what, and what you're looking for breaks them. And remember: you're not the first person who has wanted this from Doxygen. And yet, it hasn't been done yet. One of the reasons is that it's non-trivial to implement. Though honestly, I imagine another reason is that Dimitri simply doesn't believe that this is something documentation should ever actually do.

这篇关于doxygen中的分组重载的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！