Doxygen vs Javadoc

Je viens de me rendre compte dans un article du CACM que Doxygen fonctionne aussi avec Java (et plusieurs autres langages). Mais Java a déjà l’outil Javadoc. Quelqu’un peut-il expliquer quels sont les avantages et les inconvénients de l’une ou l’autre approche? Sont-ils mutuellement exclusifs? Y a-t-il un plugin Maven pour Doxygen?

Doxygen possède un certain nombre de fonctionnalités que JavaDoc ne propose pas, par exemple les diagrammes de classes pour les hiérarchies et le contexte de coopération, plus de pages de synthèse, la navigation facultative avec code source (avec la documentation), une page séparée et il peut générer des résultats au format TeX et PDF. Il permet également une personnalisation visuelle importante.

Étant donné que Doxygen prend en charge les balises JavaDoc standard, vous pouvez exécuter Doxygen sur n’importe quel code source contenant des commentaires JavaDoc. Il est même souvent logique d’exécuter le code source sans JavaDoc car les diagrammes et la navigation dans le code source peuvent aider à comprendre le code même sans la documentation. Et comme l’outil JavaDoc ignore les balises inconnues, vous pouvez même utiliser des balises Doxygen supplémentaires sans casser la génération JavaDoc.

Cela dit, je dois avouer que je n’ai pas utilisé Doxygen depuis longtemps. J’ai tendance à compter beaucoup sur mon IDE de nos jours pour fournir la même visualisation et je ne lis généralement pas JavaDoc en tant que pages HTML, mais importe les fichiers sources dans mon IDE pour générer des fly -out JavaDoc et accéder directement aux définitions. C’est encore plus puissant que ce que Doxygen a à offrir. Si vous voulez avoir de la documentation en dehors de l’IDE et que vous êtes heureux d’exécuter des outils non-Java, alors Doxygen vaut la peine d’essayer, car il ne nécessite aucune modification de votre code Java.

Je n’utiliserais Doxygen avec Java que si vous êtes novice en Java et que vous avez déjà utilisé Doxygen, ce qui réduit la courbe d’apprentissage que vous rencontreriez avec javadoc. Si vous n’avez jamais utilisé Doxygen auparavant, je restrai fidèle à javadoc, car il a été spécialement conçu pour Java. Si vous ne le connaissez pas et que vous travaillez en C ++ (ou dans d’autres langages supportés) autant que Java, Doxygen est un bon choix, car vous pourrez l’utiliser dans les deux langues.

Les deux outils sont faciles à utiliser, avec un jeu de fonctionnalités similaire. Les deux ont des plugins (ou sont pré-intégrés) pour NetBeans et Eclipse, ce qui accélère encore la génération de doc. Il y a beaucoup de chevauchement dans le style de commentaire utilisé par chacun, mais ils ne sont pas exactement les mêmes, il serait donc difficile de les mélanger (il faudrait connaître les détails des deux , sans tenir compte des fonctionnalités). spécifique à l’un ou à l’autre). Je ne l’ai jamais utilisé, mais il semble y avoir un plugin Maven pour Doxygen .

J’aime le fait qu’avec Doxygen, vous pouvez afficher les diagrammes de classes sur la même page que la documentation. En outre, j’aime le fait qu’il vous relie directement au code source, si nécessaire. Je ne sais pas si javadoc a ces fonctionnalités cependant.

L’un des grands avantages de JavaDocs est qu’ils fonctionnent simplement. Tout ce dont vous avez besoin pour les construire et les visualiser est inclus dans le JDK que vous devez déjà installer pour comstackr vos programmes.

Doxygen, par contre, peut être pénible à mettre en place et à fonctionner correctement. mais s’il est configuré correctement, il devrait pouvoir générer des fichiers PDF, RTF et DocBooks, ainsi que du HTML. Le HTML n’est pas organisé par défaut aussi bien que JavaDocs, car le fichier index.html affiche une page vierge par défaut. De même, les classes en ligne et les membres statiques peuvent nécessiter l’ajout de drapeaux spéciaux dans la documentation, et si vous souhaitez générer un PDF, vous devrez gérer les problèmes de dissortingbution de Linux sans la commande pdflatex requirejse (par exemple, Ubuntu / Mint problèmes récemment) donc si vous venez juste de l’installer et de l’exécuter, vous pouvez avoir un écran plein d’erreurs, même avec un programme simple. Par rapport à la facilité d’obtenir javadoc automatiquement lorsque vous installez l’API, l’installation de Doxygen peut être une expérience misérable. Une fois que vous avez surmonté les obstacles, vous devriez faire preuve de plus de souplesse dans le traitement de projets qui ne se limitent pas à Java.