Doxygen vs Javadoc [closed]

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?

Solution 1:

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.

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.

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.

Solution 2:

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.

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 exactly the 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.

Solution 3:

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.

Solution 4:

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.

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.