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<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.

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.

Answer 2

You can use @name tag to reach the similar functionality. Take a look at the example, that's easy.

    /**
     * @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);
    //@}

It produces the following output:

I hope this will help