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 ?
