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?