Regroupement des surcharges dans le doxygen

Dans ma bibliothèque, j’ai beaucoup de surcharges de fonctions du type:

/// \brief Does thing. /// /// \details The thing that is done is very special. template void do_stuff(const T& t); /// \brief Does thing repeatedly. /// \copydetails do_stuff() template void do_stuff(const T& t, std::size_t x);

En général, cela fonctionne bien, mais crée la même section de documentation plusieurs fois. Ce que je veux, c’est de regrouper ces fonctions. Ayez une description détaillée et chacune des surcharges annotées avec sa brève description. Je ne suis pas non plus opposé aux alias qui pourraient faire quelque chose comme ceci ou aux filtres d’entrée.

Une façon dont je pourrais imaginer ce serait:

Le résultat de la documentation devrait ressembler à ceci:

 template void do_stuff(const T& t); (1) template 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.

Bien sûr, je peux créer une nouvelle page et écrire ce type de documentation à la main, mais cela nécessiterait que je répète les déclarations de fonction sur la page, puis que des liens soient insérés dans la documentation de la fonction, mais il s’agit plus d’un hack que d’autre chose.

Y a-t-il un moyen d’y parvenir facilement? Même des allusions pour le pirater dans Doxygen seraient appréciées.

Malheureusement, Doxygen n’a pas vraiment de mécanisme pour le faire. La chose la plus proche que vous puissiez obtenir sont les groupes de membres, mais ceux-ci ne font pas ce dont vous avez besoin (ils n’apparaissent que dans la liste des prototypes de membres).

Le piratage dans Doxygen, sans modifier Doxygen lui-même, impliquerait généralement l’parsing de son format XML, ce qui pose un certain nombre de problèmes. Premièrement, son format XML est terrible pour ne rien faire d’utile (croyez-moi, j’ai essayé). Deuxièmement, il n’y a pas de syntaxe pour créer un lien entre ces fonctions. La ligne copydetails ressemble à #include en C / C ++; il ne laisse aucune trace après l’inclusion. Donc, vous ne pouvez pas dire quand il a été utilisé.

Troisièmement, vous perdriez tous les autres formats fournis par Doxygen. Vous écririez un générateur complet pour le format qui vous intéresserait.

Modifier Doxygen lui-même pour supporter ceci impliquera un certain nombre d’étapes. Tout d’abord, vous devez append une grammaire spéciale qui relie les commandes. Cela inclut la modification de la classe FuncDef pour avoir une référence à un autre FuncDef lequel elle est groupée. Deuxièmement, vous devez modifier le générateur HTML pour les générer au même endroit. Celui-ci sera beaucoup plus difficile qu’il n’y paraît. À moins que le code source interne de Doxygen se soit beaucoup amélioré depuis ma dernière visite, ce sera une douleur considérable à faire.

Le générateur HTML repose sur des hypothèses de base concernant les liens vers quoi et ce que vous recherchez, ce qui les casse. Et rappelez-vous: vous n’êtes pas la première personne à avoir souhaité cela de Doxygen. Et pourtant, cela n’a pas encore été fait. Une des raisons est que sa mise en œuvre est non sortingviale. Bien qu’honnêtement, j’imagine qu’une autre raison est que Dimisorting ne croit tout simplement pas que c’est quelque chose que la documentation devrait jamais faire.

Vous pouvez utiliser la balise @name pour atteindre la même fonctionnalité. Regardez l’exemple, c’est facile.

  /** * @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::ssortingng & tag, bool value); /** * @brief Documentation for this overload */ void append(const std::ssortingng & tag, int8_t value); void append(const std::ssortingng & tag, int16_t value); void append(const std::ssortingng & tag, int32_t value); //@}

Il produit la sortie suivante: entrez la description de l'image ici

J’espère que cela aidera