Où placer les blocs de commentaires doxygen pour une bibliothèque interne - dans H ou dans les fichiers CPP ?

Question

Le bon sens veut que les blocs de commentaires Doxygen soient placés dans les fichiers d'en-tête où se trouvent les classes, les structures, les enums, les fonctions et les déclarations. Je suis d'accord que c'est un bon argument pour les bibliothèques qui sont destinées à être distribuées sans leur source (seulement les en-têtes et les librairies avec le code objet).

MAIS... J'ai pensé à l'approche exactement inverse lorsque je développe une bibliothèque interne à l'entreprise (ou comme projet parallèle pour moi-même) qui sera utilisée avec son code source complet. Ce que je propose, c'est de placer les grands blocs de commentaires dans les fichiers d'implémentation (HPP, INL, CPP, etc.) afin de NE PAS encombrer l'interface des classes et fonctions déclarées dans l'en-tête.

Pour :

• Moins d'encombrement dans les fichiers d'en-tête, seule la catégorisation des fonctions peut être ajoutée.
• Les blocs de commentaires qui sont prévisualisés lorsqu'Intellisense par exemple est utilisé ne s'entrechoquent pas - c'est un défaut que j'ai observé lorsque j'ai un bloc de commentaires pour une fonction dans le fichier .H et que sa définition en ligne est dans le même fichier .H mais incluse dans le fichier .INL.

Cons :

• (Le plus évident) Les blocs de commentaires ne sont pas dans les fichiers d'en-tête où se trouvent les déclarations.

Alors, qu'en pensez-vous et que suggérez-vous éventuellement ?

Answer 1

Placez la documentation là où les gens la liront et l'écriront pendant qu'ils utilisent et travaillent sur le code.

Les commentaires de classe sont placés devant les classes, les commentaires de méthode devant les méthodes.

C'est la meilleure façon de s'assurer que les choses sont maintenues. Cela permet également de conserver des fichiers d'en-tête relativement légers et d'éviter le problème de la toucher le problème des personnes qui mettent à jour la documentation sur les méthodes, ce qui a pour effet de salir les en-têtes et de déclencher des reconstructions. J'ai connu des gens qui utilisaient cela comme une excuse pour écrire de la documentation. plus tard !

Answer 2

J'aime utiliser le fait que les noms peuvent être documentés à plusieurs endroits.

Dans le fichier d'en-tête, j'écris une brève description de la méthode, et je documente tous ses paramètres - ceux-ci sont moins susceptibles de changer que l'implémentation de la méthode elle-même, et s'ils changent, alors le prototype de la fonction doit être modifié de toute façon.

Je place une documentation longue dans les fichiers sources à côté de l'implémentation réelle, afin que les détails puissent être modifiés au fur et à mesure de l'évolution de la méthode.

Par exemple :

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

Answer 3

Avoir des commentaires dans l'en-tête signifie que tous les utilisateurs d'une classe doivent être recompilés si un commentaire est modifié. Pour les grands projets, les codeurs seront moins enclins à mettre à jour les commentaires dans les en-têtes s'ils risquent de passer les 20 prochaines minutes à tout reconstruire.

Et puisque vous êtes supposé lire la doc html et non parcourir le code pour la documentation, ce n'est pas un gros problème que les blocs de commentaires soient plus difficiles à localiser dans les fichiers sources.

Answer 4

En-têtes : Il est plus facile de lire les commentaires car il y a moins de "bruit" lorsqu'on regarde les fichiers.

Source : Ensuite, vous disposez des fonctions réelles pour lire tout en regardant les commentaires.

Nous utilisons simplement toutes les fonctions globales commentées dans les en-têtes et les fonctions locales commentées dans la source. Si vous le souhaitez, vous pouvez également inclure la commande copydoc pour insérer la documentation à de multiples endroits sans avoir à l'écrire plusieurs fois (c'est mieux pour la maintenance).

Cependant, vous pouvez également copier les résultats dans une documentation de fichier différente à l'aide d'une simple commande. Par exemple : :-

Mon fichier1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

MON fichier1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

Vous obtenez maintenant la même documentation pour les deux fonctions.

Cela permet de réduire le bruit dans les fichiers de code tout en obtenant la documentation écrite à un seul endroit et présentée à plusieurs endroits dans le résultat final.

Answer 5

Habituellement, je mets la documentation pour l'interface ( \param , \return ) dans le fichier .h et la documentation pour l'implémentation ( \details ) dans le fichier .c/.cpp/.m. Doxygen regroupe tout dans la documentation des fonctions/méthodes.