Doxygen 与 Javadoc

Doxygen vs Javadoc

提问by lindelof

I just realized from an article in CACM that Doxygen works with Java (and several other languages) too. But Java has already the Javadoc tool. Can someone explain what are the pros and cons of either approach? Are they mutually exclusive? Is there a Maven plugin for Doxygen?

我刚刚从 CACM 的一篇文章中意识到 Doxygen 也适用于 Java（和其他几种语言）。但是 Java 已经有了 Javadoc 工具。有人可以解释这两种方法的优缺点吗？它们是互斥的吗？是否有适用于 Doxygen 的 Maven 插件？

采纳答案by Peter Becker

Doxygen has a number of features that JavaDoc does not offer, e.g. the class diagrams for the hierarchies and the cooperation context, more summary pages, optional source-code browsing (cross-linked with the documentation), additional tag support such as @todo on a separate page and it can generate output in TeX and PDF format.It also allows a lot of visual customization.

Doxygen 有许多 JavaDoc 没有提供的特性，例如层次结构和合作上下文的类图、更多的摘要页面、可选的源代码浏览（与文档交叉链接）、额外的标签支持，例如 @todo on一个单独的页面，它可以生成 TeX 和 PDF 格式的输出。它还允许大量的可视化定制。

Since Doxygen supports the standard JavaDoc tags you can run Doxygen on any source code with JavaDoc comments on it. It often can even make sense to run on source code without JavaDoc since the diagrams and source code browsing can help understanding code even without the documentation. And since the JavaDoc tool ignores unknown tags you can even use additional Doxygen tags without breaking JavaDoc generation.

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

Having said all this I must admit that I haven't used Doxygen for a long time. I tend to rely heavily on my IDE nowadays to provide the same visualization and I usually don't read JavaDoc as HTML pages but import the source files into my IDE so it can generate JavaDoc flyouts and I can jump to the definitions. That's even more powerful than what Doxygen has to offer. If you want to have documentation outside the IDE and are happy to run non-Java tooling then Doxygen is worth a try since it doesn't require any change to your Java code.

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

回答by Bill the Lizard

I'd only use Doxygen with Java if you're new to Java and you've used Doxygen before, reducing the learning curve you'd experience with javadoc. If you haven't used Doxygen before, I'd stick with javadoc, since it was specifically designed with Java in mind. If you don't know either one, and you work in C++ (or other supported languages) as much as you do Java, Doxygen is a good choice, as you'll be able to use it for both languages.

如果您不熟悉 Java 并且以前使用过 Doxygen，我只会将 Doxygen 与 Java 一起使用，从而减少您在使用 javadoc 时遇到的学习曲线。如果您以前没有使用过 Doxygen，我会坚持使用 javadoc，因为它是专门为 Java 设计的。如果您不知道其中任何一种，并且您使用 C++（或其他支持的语言）和 Java 一样多，那么 Doxygen 是一个不错的选择，因为您可以将它用于两种语言。

Both tools are easy to use, with a similar feature set. Both have plugins (or are pre-built in) for NetBeans and Eclipse making it even faster to generate doc. There is a lot of overlap in the comment style used by each, but they're not exactlythe same, so it would be difficult to mix them together (you'd have to know the details of both, leaving out any features that are specific to one or the other). I've never used it, but there does seem to be a Maven plugin for Doxygen.

这两种工具都易于使用，具有相似的功能集。两者都有适用于 NetBeans 和 Eclipse 的插件（或预先内置），从而可以更快地生成文档。每个人使用的注释样式有很多重叠，但它们并不完全相同，因此很难将它们混合在一起（您必须了解两者的详细信息，而忽略了任何特定于一个或另一个）。我从未使用过它，但似乎确实有一个适用于 Doxygen的Maven 插件。

回答by dr_pepper

I like the fact that with Doxygen, you can get class diagrams displayed on the same page as the documentation. Also, I like the fact that it links you directly to the source code, if needed. I am not aware if javadoc has these features though.

我喜欢这样一个事实，即使用 Doxygen，您可以将类图与文档显示在同一页面上。此外，如果需要，我喜欢它直接将您链接到源代码的事实。我不知道 javadoc 是否有这些功能。

回答by MintUser

One big advantage of JavaDocs is that they just work. Everything needed to build and view them is included in the JDK that you already need to have installed for compiling your programs.

JavaDocs 的一大优势是它们可以正常工作。构建和查看它们所需的一切都包含在您为编译程序而需要安装的 JDK 中。

Doxygen, on the other hand can be a pain to set up and get working correctly. but if it is set up correctly it should be able to generate PDFs, RTFs, and DocBooks, as well as HTML. The HTML is not organized as well by default as JavaDocs since the index.html brings up a blank page by default. Also, inline classes and static members may need special flags to be included in documentation, and if you want to generate a PDF you may have to deal with hassles of your distribution of Linux not having the needed pdflatex command (e.g. Ubuntu/Mint have had problems recently) so if you just apt-get install it and run you may get a screen full of errors even with a simple program. Compared to the ease of getting javadoc automatically when you install the API, Doxygen setup can be a miserable experience. Once you overcome the hurdles, it should be more flexible in dealing with projects involving more than just java, though.

另一方面，Doxygen 的设置和正常工作可能会很痛苦。但如果设置正确，它应该能够生成 PDF、RTF 和 DocBooks，以及 HTML。默认情况下，HTML 的组织方式不如 JavaDocs 好，因为 index.html 默认情况下会显示一个空白页面。此外，内联类和静态成员可能需要在文档中包含特殊标志，如果您想生成 PDF，您可能不得不处理 Linux 发行版中没有所需 pdflatex 命令的麻烦（例如 Ubuntu/Mint最近有问题）所以如果你只是 apt-get 安装它并运行你可能会看到一个充满错误的屏幕，即使是一个简单的程序。与安装 API 时自动获取 javadoc 的容易程度相比，Doxygen 设置可能是一种悲惨的体验。一旦你克服了障碍，