Группировка перегрузок в doxygen

В моей библиотеке у меня много перегрузок функций формы:

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

Конечно, я могу создать новую страницу и написать такую ​​документацию но мне потребовалось бы повторить объявления функций на страницу, а затем перфорировать ссылки в действительную функцию документация, но это скорее взлом, чем что-либо еще.

Есть ли способ достичь этого легко? Даже намеки взломать его в doxygen будет оценен.

ОТВЕТЫ

Ответ 1

К сожалению, у Doxygen действительно нет механизма для этого. Самое близкое, что вы можете получить, это группы участников, но они не делают то, что вам нужно (они появляются только в списке прототипов участников).

Взломать его в Doxygen, не изменяя сам Doxygen, как правило, будет включать в себя анализ XML-формата, который представляет собой ряд проблем. Во-первых, его формат XML ужасен для того, чтобы делать что-нибудь полезное (поверьте, я пробовал). Во-вторых, нет синтаксиса для создания связи между этими функциями. Строка copydetails похожа на #include в C/С++; он не оставляет следов после включения. Поэтому вы не можете сказать, когда он был фактически использован.

В-третьих, вы выбрасываете все другие форматы, которые предоставляет Doxygen. Вы бы написали полный генератор для любого формата, который вас интересует.

Модификация самого Doxygen для поддержки этого будет включать в себя несколько шагов. Во-первых, вам нужно добавить специальную грамматику, которая связывает команды. Это включает в себя изменение класса FuncDef для ссылки на другой FuncDef, с которым он сгруппирован. Во-вторых, вам нужно изменить генератор HTML, чтобы сгенерировать их в одном месте. Это будет намного сложнее, чем кажется. Если только исходный код Doxygen не стал намного лучше с тех пор, как я его последний раз видел, это будет серьезной болью.

Генератор HTML имеет некоторые базовые предположения о том, какие ссылки на что и что вы ищете, разрывает их. И помните: вы не первый человек, который хотел этого от Doxygen. И все же это еще не сделано. Одна из причин заключается в том, что он не является тривиальным для реализации. Хотя честно, я полагаю, что другая причина заключается в том, что Димитрий просто не верит, что это то, что документация должна когда-либо делать.

Ответ 2

Вы можете использовать тег @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

Я надеюсь, что это поможет