Doxygen vs Javadoc [fermé]
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 m'expliquer quels sont les avantages et les inconvénients de l'un et l'autre? Sont-elles incompatibles? Existe-t-il un plugin Maven pour Doxygen?
4 réponses
Doxygen a un certain nombre de fonctionnalités que JavaDoc N'offre pas, par exemple les diagrammes de classe pour les hiérarchies et le contexte de coopération, plus de pages de résumé, la navigation facultative de code source (en lien avec la documentation), le soutien d'étiquette supplémentaire tel que @todo sur une page séparée et il peut générer la production en TeX et Format PDF.Il permet également beaucoup de personnalisation visuelle.
puisque Doxygen prend en charge les tags JavaDoc standard, vous pouvez exécuter Doxygen sur n'importe quelle source le code avec JavaDoc commente. Il est souvent même logique d'exécuter sur du code source sans JavaDoc puisque les diagrammes et la navigation sur le code source peuvent aider à comprendre le code même sans la documentation. Et comme L'outil JavaDoc ignore les étiquettes inconnues, vous pouvez même utiliser des étiquettes Doxygen supplémentaires sans casser la génération JavaDoc.
cela dit, je dois admettre que je n'ai pas utilisé Doxygen depuis longtemps. J'ai tendance à compter fortement sur mon IDE de nos jours pour fournir le même la visualisation et la j'ai l'habitude de ne pas lire la JavaDoc des pages HTML, mais importer les fichiers source dans mon IDE de sorte qu'il peut générer la JavaDoc des menus volants et je peux sauter les 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 le coup d'essayer car il ne nécessite aucune modification de votre code Java.
Je n'utiliserais Doxygen avec Java que si vous êtes nouveau en Java et que vous avez déjà utilisé Doxygen auparavant, réduisant ainsi la courbe d'apprentissage que vous rencontreriez avec javadoc. Si vous n'avez jamais utilisé Doxygen avant, je m'en tiendrais à javadoc, car il a été spécifiquement conçu avec Java à l'esprit. Si vous ne connaissez ni L'un ni l'autre, et que vous travaillez en C++ (ou dans d'autres langues supportées) autant que vous faites Java, Doxygen est un bon choix, car vous pourrez l'utiliser pour les deux langues.
les deux outils sont facile à 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 le rend encore plus rapide pour générer doc. Il y a beaucoup de chevauchement dans le style de commentaire utilisé par chacun, mais ils ne sont pas exactement le même, il serait donc difficile de les mélanger ensemble (vous auriez à connaître les détails de les deux , en excluant toutes les caractéristiques qui sont spécifiques à l'un ou l'autre). Je n'ai jamais utilisé, mais il ne semble pas être un plugin Maven pour Doxygen .
j'aime le fait qu'avec Doxygen, vous pouvez obtenir des diagrammes de classe affiché sur la même page que la documentation. Aussi, 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.
un grand avantage de JavaDocs est qu'ils ne font que fonctionner. Tout ce qui est nécessaire pour les construire et les visualiser est inclus dans le JDK que vous devez déjà avoir installé pour compiler vos programmes.
Doxygen, d'autre part peut être une douleur à mettre en place et de travailler correctement. mais s'il est configuré correctement, il devrait être capable de générer des fichiers PDF, RTFs, DocBooks et HTML. Le HTML n'est pas aussi bien organisé par défaut que JavaDocs depuis l'index.html apporte un page blanche par défaut. En outre, les classes inline et les membres statiques peuvent avoir besoin de drapeaux spéciaux pour être inclus dans la documentation, et si vous voulez générer un PDF, vous pouvez avoir à faire face aux tracas de votre distribution de Linux n'ayant pas la commande pdflatex nécessaire (par exemple Ubuntu/Mint ont eu des problèmes récemment) donc si vous juste apt-get install it et exécuter, vous pouvez obtenir un écran plein d'erreurs, même avec un programme simple. Comparé à la facilité d'obtenir javadoc automatiquement lorsque vous installez L'API, Doxygen l'installation peut être une expérience misérable. Une fois que vous surmontez les obstacles, il devrait être plus flexible dans le traitement des projets impliquant plus que juste java, cependant.