多克辛vs Javadoc

我刚刚从CACM的一篇文章中认识到,Doxygen也可以和Java(以及其他几种语言)一起工作。 但是Java已经有了Javadoc工具。 有人可以解释两种方法的优缺点吗? 它们是相互排斥的吗? 有Doxygen的Maven插件吗?

Doxygen有一些JavaDoc没有提供的function,例如层次结构和合作上下文的类图,更多的汇总页面,可选的源代码浏览(与文档交叉链接),额外的标签支持,例如@todo on一个单独的页面,它可以生成TeX和PDF格式的输出。它也允许很多的可视化定制。

由于Doxygen支持标准的JavaDoc标签,所以你可以在任何带有JavaDoc注释的源代码上运行Doxygen。 在没有JavaDoc的情况下运行源代码通常甚至是有意义的,因为即使没有文档,图表和源代码浏览也可以帮助理解代码。 而且由于JavaDoc工具会忽略未知标签,所以您甚至可以使用额外的Doxygen标签而不会中断JavaDoc生成。

说完这一切,我必须承认,我很久没有使用Doxygen了。 我倾向于现在依赖我的IDE来提供相同的可视化,而且我通常不会将JavaDoc作为HTML页面读取,而是将源文件导入到我的IDE中,以便生成JavaDocpopup窗口,并跳转到定​​义。 这比Doxygen所提供的更强大。 如果你想在IDE之外有文档,并且很乐意运行非Java工具,那么Doxygen值得一试,因为它不需要对你的Java代码进行任何改变。

如果您是Java新手,并且之前使用过Doxygen,那么我只会在Java中使用Doxygen,从而减less您使用javadoc所学到的学习曲线。 如果你之前没有使用Doxygen,我会坚持使用javadoc,因为它是专门为Javadevise的。 如果你不了解任何一个,而且你使用C ++(或者其他支持的语言)和Java一样工作,那么Doxygen是一个不错的select,因为你可以在两种语言中使用它。

这两个工具都很容易使用,具有相似的function集。 对于NetBeans和Eclipse,两者都有插件(或者是预先构build的),这使得生成文档的速度更快。 在每个评论风格中有很多重叠,但是它们并不完全一样,所以很难将它们混合在一起(你必须知道两者的细节,而忽略了所有的特征具体到一个或另一个)。 我从来没有使用过,但似乎是Doxygen的Maven插件 。

我喜欢使用Doxygen的事实,您可以在文档的同一页面上显示类图。 另外,如果需要的话,我喜欢直接链接到源代码的事实。 我不知道如果javadoc有这些function。

JavaDocs的一大优势是它们只是工作。 构build和查看它们所需的所有东西都包含在JDK中,您必须安装它才能编译程序。

另一方面,Doxygen可能是一个痛苦的build立和正确工作。 但如果设置正确,它应该能够生成PDF,RTF,DocBook以及HTML。 由于缺省情况下index.html会popup一个空白页面,因此默认情况下,HTML的组织方式与JavaDocs不同。 另外,内联类和静态成员可能需要特殊的标志才能包含在文档中,如果你想生成一个PDF,你可能不得不处理Linux分发的麻烦,而没有需要的pdflatex命令(例如Ubuntu / Mint已经有问题最近),所以如果你只是apt-get安装并运行你可能会得到一个屏幕充满错误,即使是一个简单的程序。 与安装API时自动获取javadoc的方便性相比,Doxygen设置可能是一个痛苦的经历。 一旦你克服了障碍,它应该更灵活地处理涉及不仅仅是Java的项目。