web-dev-qa-db-fra.com

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

Le bon sens indique que les blocs de commentaires Doxygen doivent être placés dans les fichiers d'en-tête où se trouvent les classes, structures, énumérations, fonctions, déclarations. Je suis d'accord que c'est un argument valable pour des bibliothèques qui sont censées être distribuées 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) 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 s'affrontent 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 inclus à partir du fichier .INL.

Inconvénients:

  • (L'é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 vous suggérez éventuellement?

documentationcommentsdoxygen
91
Singulus

Placez la documentation là où les gens vont la lire et l'écrire pendant 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 le meilleur moyen 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 provoque l'encrassement des en-têtes et déclenche des reconstructions. Je sais que les gens l'utilisent comme excuse pour écrire de la documentation plus tard!

72
Andy Dent

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 s'ils le font, alors le prototype de fonction doit être changé dans tous les cas .

J'ai mis de la 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;
}
65
Daniel Buckmaster

Le fait d'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 minutes à tout reconstruire.

Et .. puisque vous êtes censé lire le document html et ne pas 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 source.

17
ErikJ

En-têtes: Plus facile à lire les commentaires car il y a moins de "bruit" en regardant les 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 une autre documentation de fichier 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 la documentation écrite en un seul endroit est présentée à plusieurs endroits dans la sortie finale.

11
eaanon01

Je mets tout dans le fichier d'en-tête.

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

2
graham.reeds

Habituellement, je mets la documentation de 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.

2
mouviciel

J'utilise QtCreator pour la programmation. Une astuce très utile consiste à cliquer-Ctrl 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 devraient être situés dans le fichier d'en-tête!

1
Sinclair