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

Le bon sens dit que les blocs de commentaires Doxygen doivent être placés dans les fichiers d'en-tête où se trouvent les classes, les structures, les énumérations, les fonctions et les déclarations. Je conviens que c'est un argument valable pour une bibliothèque qui est censée être distribuée sans sa source (uniquement les en-têtes et les bibliothèques avec le code objet).

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

Avantages:

• 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 lorsque Intellisense par exemple est utilisé ne sont pas en conflit - 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 j'ai sa définition en ligne dans le même fichier .H mais inclus à partir du fichier .INL.

Les inconvénients:

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

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

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

Les commentaires de classe passent 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. Il garde également vos fichiers d'en-tête relativement maigres et évite le problème touchant des personnes qui mettent à jour les documents de méthode, ce qui entraîne des en-têtes sales et déclenche des reconstructions. J'ai en fait connu des gens qui l'utilisent comme excuse pour rédiger de la documentation plus tard!

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 documente tous ses paramètres - ceux-ci sont moins susceptibles de changer que l'implémentation de la méthode elle-même, et si c'est le cas, le prototype de fonction doit être changé dans tous les cas .

J'ai mis une documentation au format long dans les fichiers source à côté de l'implémentation réelle, afin que les détails puissent être modifiés à mesure que la méthode évolue.

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;
}

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 censé lire le doc html et ne pas parcourir le code pour la documentation, ce n'est pas un gros problème que les blocs de commentaires sont plus difficiles à localiser dans les fichiers source.

En-têtes: Plus facile à lire les commentaires car il y a moins d'autres "bruits" lors de la visualisation des fichiers.

Source: Ensuite, vous avez les fonctions réelles disponibles pour la lecture 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 à plusieurs endroits sans avoir à l'écrire plusieurs fois (mieux pour la maintenance)

Vous pouvez cependant également copier les résultats dans différents fichiers de documentation avec 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 sur les deux fonctions.

Cela vous donne moins de bruit dans les fichiers de code en même temps que vous obtenez la documentation écrite à un endroit présenté à plusieurs endroits dans la sortie finale.

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

J'ai tout mis dans le fichier d'en-tête.

Je documente tout, mais n'extrais que généralement l'interface publique.

J'utilise QtCreator pour la programmation. Une astuce très utile consiste à faire un Ctrl-clic sur une fonction ou une méthode pour obtenir la déclaration dans le fichier d'en-tête.

Lorsque la méthode est commentée dans le fichier d'en-tête, vous pouvez trouver rapidement les informations que vous recherchez. Donc pour moi, les commentaires doivent être situés dans le fichier d'en-tête!

En C ++, l'implémentation peut parfois être divisée entre les modules d'en-tête et .cpp. Ici, il semble plus simple de mettre la documentation dans le fichier d'en-tête car c'est le seul endroit où toutes les fonctions et méthodes publiques sont garanties.