Discussion :

[Mac LAK]

Je pense que la différence principale est que je ne modifie pas les headers de la bibliothèque standard. Alors dans ce cas, avoir un accès lecture seule à de la documentation plutôt qu'aux headers eux même, pourquoi pas. Mais pour de code que je suis appelé à faire évoluer, cette documentation inclue dans le header megène plus qu'elle ne m'aide (mais le résultat de généré par cette doc m'est bien utile quand je me place en simple utilisateur du code).

Pour ceci, j'utilise deux points, pour ma part :

• Je déplace la documentation des groupes / pages soit dans un fichier annexe peu modifié (genre stdafx.h, fichier d'import/export DLL ou équivalent), soit en fin de fichier.
• La documentation des fonctions est la plus compacte possible, et j'utilise à outrance le repli de code.

En général, ma doc Doxygen est alors d'un même niveau de "pollution" que les simples commentaires "normaux", et ne prends guère plus de temps à écrire.
Je reconnais toutefois qu'il faut en prendre l'habitude, et avoir les bons outils à sa disposition.

Le point important que je vois à ça, c'est surtout que dans le cas d'un header vide de commentaires, tu pleures le jour où la doc est paumée et/ou non mise à jour : tu dois verser dans le reverse-engineering pour t'y retrouver.
Au moins, avec une doc incluse dans le source, c'est difficile de paumer la doc !

(et accessoirement, je connais un collègue qui aura plus tendance à ouvrir le .h de la SL qu'à lire la doc...)

C'est son droit le plus strict d'être masochiste, hein...