Tuesday, June 13, 2006

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!

6 comments:

bobk5444 said...

Hello,

I've been trying to find out if Doxygen can read one's directory of input C++ source code and create a new directory containing the same source code but where the new source code has hyperlinks to keys references throughout the directory?

Xref-tech has this kind of capability for JAVA code and free, and has it for C++ as well, but the C++ version is fairly expensive, but i'm wondering if Doxygen has this capability?

Thanks very much!
BobK

Guillaume Delahutte said...

You should try NaturalDocs too. Even if it has less features than doxygen, it's interesting.

rumen said...

I am about 10 years C++ developer and 3-4 years java developer, so I had same question on my mind. And I did the same research.

I think its a quite huge topic to discuss therefore I am just "briefly" sharing my opinion.

Java is not C++, so and documenting Java might be different.
Maybe one should study Javadoc in deep details as he/she knows Doxygen and then make comparison.

For me I choose to be coherent. And I use Javadoc.
Yes, html tags are a pain in the ass. But Doxygen needs them too.
And the example given by the author looks like a propaganda to me ;)
What about the third form of the @see tag?
I think the problem is the way of thinking - when thinking in Javadoc Doxygen seems difficult and vice versa.

Well, it is not easy to switch from the well-known Windows to Linux either, it was annoying for me to switch from C++ to Java, from Doxygen to Javadoc... Yes it was. But when you switch to the right thinking - its even better. So it is your choice. I know one thing - striving to use C++ strengths while coding in Java is a death sentence. Well, not death but unhappiness.
Currently I really prefer Java. And I apologize to all my friends I insulted with saying "Java suxx" when we were arguing on the eternal question - C or Java - a few years ago :)

So, I think it is the same with Doxygen and Javadoc.

Jakub Gemrot said...

Does refactoring in C++ changes also doxygen comments? Invaluable feature to me as a Java developer.

Litéra said...

very nice comparison between Doxygen Vs Javadoc.

Thanks
Document Comparison

alexandroid said...

@rumen But programmers read code and comments in it all the time when working, compare that when they browse and read generated documentation.

Why inline comment I should read in code, but class comment I should read in the browser?

Why make my eyes bleed when read text+HTML mix when I could achieve the same result with a little bit more intelligence from the tool which covers 99% of the commenting need and save HTML for really difficult cases?

I also migrated from C++/Doxygen to Java/Javadoc and is astonished how low level Javadoc is. No wonder why the Java code I read has very little comments - people simply avoid them and write full HTML web-pages instead, but only when they really are forced to.

If Doxygen has limitations, it is up for technology to improve, not for people to adjust for the technology.