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

97

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?

Singulus
la source

Réponses:

77

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!

Andy Dent
la source
11
J'ai eu un rappel douloureux de la raison pour laquelle les documents dans les en-têtes devraient être évités - un vice-président senior m'a dit de mettre des commentaires de méthode dans la déclaration de classe et je me suis retrouvé à enregistrer les modifications de commentaires pour plus tard, car frapper ces en-têtes déclenche un temps de construction de 45 minutes !
Andy Dent
7
Pas de vote négatif, juste des questions: si j'essaie de comprendre ce que fait une API (même interne), je préfère ne pas avoir à ouvrir le .cpp et parcourir tout le code pour trouver la documentation. J'admets que ce serait pénible si vous documentiez plus que la vue du client sur ce que fait la méthode (comme comment elle le fait), mais vous ne devriez pas le faire de toute façon, non?
TED
8
L'intérêt d'utiliser Doxygen pour générer votre documentation est d'avoir la documentation générée accessible. Nous avons un serveur Web interne où va la sortie Doxygen et nous pouvons ensuite utiliser des liens vers des pages sur ce serveur dans les discussions. Cela relie également la documentation de classe ou de méthode avec des pages supplémentaires traitant de problèmes de conception plus larges.
Andy Dent
1
Décider dans quelle mesure la discussion sur la mise en œuvre devrait être publique est une question intéressante. Sûrement s'il y a un algorithme particulier ou des effets secondaires, je préférerais les connaître en tant que client de la bibliothèque. Parfois, seul le responsable doit savoir et Doxygen dispose d'un moyen simple de marquer les sections conditionnelles, vous pouvez donc générer différents documents pour différents points de vue.
Andy Dent
76

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;
}
Daniel Buckmaster
la source
3
J'aime cette méthode, mais elle semble incompatible avec AUTOBRIEF. Je serais intéressé de savoir s'il existe une solution de contournement de configuration pour éliminer les multiples mémoires qui sont produits.
Aaron Wright
J'aime aussi cette méthode, elle offre un bon équilibre dans la mise en œuvre.
Xofo
Je ne parviens pas à reproduire cette méthode sur ma machine, en utilisant Doxygen 1.8.15. La documentation des paramètres n'apparaît pas, seulement les descriptions brèves et détaillées.
punyidea
1
Addendum: Changer le placement de la description détaillée à l'intérieur du bloc de la fonction a fait ce travail pour moi. La description est maintenant ajoutée à la fin des descriptions dans les documents d'en-tête.
punyidea
18

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.


la source
Correct, mais c'est un gros problème s'il s'agit d'une bibliothèque dynamique récupérée à partir d'un artificiel et que vous n'avez pas les fichiers sources :-)
DrumM
12

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.

eaanon01
la source
2
quand le bloc est-il copié?
Mert Can Ergün
2

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.

mouviciel
la source
2

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

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

graham.reeds
la source
2

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!

Sinclair
la source
-1

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.

Kelvin
la source