Grouping overloads in doxygen

Question

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

        

Answer 1

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.