Doxygen Versus Javadoc

As a C++ programmer accustomed to Doxygen I was always curious to learn a language where automatic code generation was taken seriously and supported as standard. When I finally moved over to a Java project I was shocked to discover how obtrusive and "in your face" Javadoc is. It seems to go out of it's way to get in my way!

By comparison Doxygen is about as good as it gets. It is designed to produce great looking documentation with the least amount of developer effort. Javadoc, on the other hand expects developer contribution in areas that I feel are perfect candidates for automation. Take paragraphs for example; Javadoc expects the developer to use the standard HTML paragraph tag <p> in the comments. Why? Why? Why? Surely it would be quite simple to automatically detect an empty line as the start of a new paragraph?

Many Java developers - including the Javadoc development team I'm sure - would take the view that HTML is the obvious choice for Javadoc text formatting and I agree that, at least theoretically it seems an obvious choice. In practice however, there is simply no need for HTML for simple text formatting such as marking text as bold, italic, etc. Using HTML for anything else is overkill in a source comment and only serves to make the comment unreadable in source form.

Examine the following Javadoc comment:

/**
  This is <i>the</i> Rectangle class.  
  <p> 
  Refer to <a href="./doc-files/shapes-overview.html">
  shape-overview</a> for more details.
  <p>
  There are four types of supported {@link Shape}:
  <ul>
    <li>{@link Rectangle} (this class)</li>
    <li>{@link Circle}</li>
    <li>{@link Square}</li>
    <li>{@link Triangle}</li>
  </ul>
*/

Here is the equivalent comment using Doxygen:

/**
  This is <i>the</i> Rectangle class.

  Refer to \ref shape-overview for more details.

  There are four types of supported Shape:
    - Rectangle (this class)
    - Circle
    - Square
    - Triangle
*/

Points to note in this comparison are:

• Doxygen will automatically recognise all code objects and insert a hyperlink, hence there is no need for a @link tag.


• Doxygen provides a very convenient shorthand notation for lists.


• Notice how easy it is to reference another page in the documentation compared to Javadoc's use of the HTML HREF tag.

The most important problem with the Javadoc comment in the comparison is how much I need to concentrate on formatting issues while writing it. When writing Javadoc I am constantly thinking about what should and shouldn't be linked, whether the list will look right, etc. This is frustrating because, while I do want to document my code well I also want to focus on coding. Therefore, due to the effort involved in commenting Javadoc-style, I usually focus on the code while in a heavy development session then I go through and document everything afterwards. I'd much rather document my code incrementally during development, but Javadoc, it seems, almost strives to make this as difficult as possible! Doxygen allows me to use HTML where it works well (marking text as bold, etc.) but also supports convenient shorthand for lists and is intelligent enough to realise that an empty line should be converted into the start of a new paragraph in the generated documentation.

I have provided the generated documentation of the Shape example for both Doxygen and Javadoc so you can decide for yourself which approach you prefer. Note the following Doxygen features:

• Doxygen provides a hyperlinked graphical class hierarchy although it is initially well hidden! From the main page, select the "Classes" tab, then the "Class Hierarchy" sub-tab then click "Goto the graphical hierarchy".
  
  
• Doxygen will produce a hyperlinked graphical class hierarchy for every class at the top of the page.



• In the Doxygen page for Rectangle, notice that there is a link to the source code. Doxygen generates a hyperlinked HTML source browser for all source code.



• Doxygen has a "\todo" command and will automatically generated a hyperlinked todo page. Handy! It supports a bug list and test list.



• Doxygen provides many more features including full support for graphical class charts, grouping of classes, mathematical formulas, multiple output formats (HTML, LATEX, PDF, man pages, HTMLHelp, etc.).

So what do you think? If you are a Java developer are you surprised how powerful Doxygen is or do you feel that the Javadoc approach is better? I'd be interested to here from developers who really prefer the Javadoc approach as it baffles me, that's for sure!