Faire une documentation de qualité, c'est un métier et ça demande d'y passer du temps.
En fait, Doxygen peut même être nuisible pour ce genre de choses. L'idée est de mettre la documentation et le code dans le même fichier, en se disant que comme ça les gens vont peut-être mieux arriver à garder les deux synchronisés. Mais l'inconvénient, c'est que ça conduit souvent à une documentation qui est seulement une paraphrase du code: on va sagement mettre un gros commentaire Doxygen au début de chaque fonction et bêtement répéter ce que fait le code dedans. ça n'a aucun intérêt. Une documentation est utile quand elle arrive à prendre de la hauteur et à décrire l'architecture sans trop rentrer dans les détails.
Il y a des cas ou Doxygen marche plutôt bien, par exemple pour documenter les APIs d'un module. Il est possible de l'utiliser pour faire une documentation d'architecture complète, mais ça reste beaucoup de travail. Et surtout, c'est pénible de devoir inclure toute cette documentation dans les fichiers source, dont ça encombre la lecture. J'ai en tête un projet qui a trouvé une solution en mettant les commentaires Doxygen dans des fichiers séparés du code source pour éviter ce problème. Mais du coup, Doxygen n'a plus grand intérêt, si ce n'est de parser les fichiers .h du projet pour vérifier que les APIs documentées sont bien celles qui sont implémentées.
[^] # Re: la spec, c'est le code
Posté par pulkomandy (site web personnel, Mastodon) . En réponse à la dépêche Développement très rapide d’applications libres : Extended Man/XML Frames. Évalué à 5.
Doxygen ce n'est pas de la magie.
Faire une documentation de qualité, c'est un métier et ça demande d'y passer du temps.
En fait, Doxygen peut même être nuisible pour ce genre de choses. L'idée est de mettre la documentation et le code dans le même fichier, en se disant que comme ça les gens vont peut-être mieux arriver à garder les deux synchronisés. Mais l'inconvénient, c'est que ça conduit souvent à une documentation qui est seulement une paraphrase du code: on va sagement mettre un gros commentaire Doxygen au début de chaque fonction et bêtement répéter ce que fait le code dedans. ça n'a aucun intérêt. Une documentation est utile quand elle arrive à prendre de la hauteur et à décrire l'architecture sans trop rentrer dans les détails.
Il y a des cas ou Doxygen marche plutôt bien, par exemple pour documenter les APIs d'un module. Il est possible de l'utiliser pour faire une documentation d'architecture complète, mais ça reste beaucoup de travail. Et surtout, c'est pénible de devoir inclure toute cette documentation dans les fichiers source, dont ça encombre la lecture. J'ai en tête un projet qui a trouvé une solution en mettant les commentaires Doxygen dans des fichiers séparés du code source pour éviter ce problème. Mais du coup, Doxygen n'a plus grand intérêt, si ce n'est de parser les fichiers .h du projet pour vérifier que les APIs documentées sont bien celles qui sont implémentées.