Doxygen vs Javadoc
Je viens de réaliser à partir d'un article dans CACM que Doxygen fonctionne avec Java (et plusieurs autres langues) aussi. Mais Java a déjà l'outil Javadoc. Quelqu'un peut-il expliquer Quels sont les avantages et les inconvénients des deux approches? S'excluent-elles mutuellement? Existe-t-il un plugin Maven pour Doxygen?
Doxygen a un certain nombre de fonctionnalités que JavaDoc n'offre pas, par exemple les diagrammes de classes pour les hiérarchies et le contexte de coopération, plus de pages récapitulatives, la navigation facultative dans le code source (croisée avec la documentation), la prise en charge de balises supplémentaires telles que @todo sur une page séparée et il peut générer une sortie dans TeX et PDF format. Il permet également beaucoup de personnalisation visuelle.
Étant donné que Doxygen prend en charge les balises JavaDoc standard, vous pouvez exécuter Doxygen sur n'importe quel code source avec des commentaires JavaDoc dessus. Souvent, il peut même être judicieux de s'exécuter sur du 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 puisque l'outil JavaDoc ignore les balises inconnues, vous pouvez même utiliser des balises Doxygen supplémentaires sans interrompre la génération JavaDoc.
Cela dit, je dois admettre que je n'ai pas utilisé Doxygen depuis longtemps. De nos jours, je compte beaucoup sur mon IDE pour fournir la même visualisation et je ne lis généralement pas JavaDoc en tant que pages HTML, mais j'importe les fichiers source dans mon IDE afin qu'il puisse générer JavaDoc flyouts et je peux passer aux définitions. C'est encore plus puissant que ce que Doxygen a à offrir. Si vous souhaitez avoir de la documentation en dehors du IDE et êtes heureux d'exécuter des outils non Java, alors Doxygen vaut la peine d'être essayé car il ne nécessite aucune modification de votre code Java.
Je n'utiliserais Doxygen qu'avec Java si vous êtes nouveau à Java et que vous avez déjà utilisé Doxygen, réduisant ainsi la courbe d'apprentissage avec laquelle vous vivriez) javadoc. Si vous n'avez jamais utilisé Doxygen auparavant, je m'en tiendrai à javadoc, car il a été spécialement conçu avec Java en tête. Si vous ne connaissez aucun des deux et que vous travaillez dans C++ (ou d'autres langages pris en charge) autant que Java, Doxygen est un bon choix, car vous pourrez l'utiliser pour les deux langages.
Les deux outils sont faciles à utiliser, avec un ensemble de fonctionnalités similaires. Les deux ont des plugins (ou sont pré-intégrés) pour NetBeans et Eclipse ce qui rend encore plus rapide la génération de doc. Il y a beaucoup de chevauchements dans le style de commentaire utilisé par chacun, mais ils ne sont pas exactement identiques, il serait donc difficile de les mélanger ensemble (vous devez connaître les détails de les deux , en laissant de côté toutes les fonctionnalités spécifiques à l'une 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 obtenir des diagrammes de classes affichés 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 possède ces fonctionnalités.
Un gros avantage des JavaDocs est qu'ils fonctionnent simplement. Tout le nécessaire pour les construire et les visualiser est inclus dans le JDK que vous devez déjà avoir installé pour compiler vos programmes.
L'oxygène, en revanche, peut être pénible à installer et à fonctionner correctement. mais s'il est correctement configuré, il devrait être capable de générer des PDF, des RTF et des DocBooks, ainsi que du HTML. Le HTML n'est pas organisé aussi bien par défaut que JavaDocs puisque le index.html affiche une page vierge par défaut. En outre, les classes en ligne et les membres statiques peuvent nécessiter des drapeaux spéciaux pour être inclus dans la documentation, et si vous souhaitez générer un PDF vous devrez peut-être faire face aux tracas de votre distribution de Linux n'ayant pas le nécessaire Commande pdflatex (par exemple, Ubuntu/Mint a eu des problèmes récemment) donc si vous venez de l'installer et de l'exécuter, vous pouvez obtenir un écran plein d'erreurs même avec un programme simple. Comparé à la facilité d'obtenir automatiquement javadoc lorsque vous installez l'API , La configuration de Doxygen peut être une expérience misérable. Une fois que vous avez surmonté les obstacles, elle devrait être plus flexible dans le traitement de projets impliquant plus que Java, cependant.