Javadoc

Javadoc is built in to Java, but I think they botched it. It's clear that they didn't care deeply: JLS3 grammar doesn't mention javadoc at all, and the JLS doesn't specify it, hardly even mentions it… the word stepchild sounds more appropriate than does builtin, in my oh-so-humble opinion.

There are many things I don't like about the result, and few things I do like.

There's too much typing for not enough benefit. Why should I have to write {@link java.awt.Panel} in order to get a link to the Panel class? Why six characters for something that's as common as @param? In qdoc/udoc I used \a for that, and designed it to fit in the prose.

As a result, many simple functions can be documented well in 1-2 sentences using udoc, but require n+1 in javadoc (one for the function, n for the @params). That may not matter for a professional writer, but typical programmers are different.

Also, why type java.awt.Panel instead of just Panel? Java allows abbreviation (using import java.awt.Panel) in the source code, why doesn't that import apply to documentation as well? This may be a minor point, but it's enough of a hassle that they added import for the source code.

Javadoc lacks heuristics. @link is a good example: In qdoc, I hacked together heuristics to add links for classes, functions, etc., and got the result about right. Javadoc asks humans to decide which class names etc. should be links. Thousands of low-value decisions that the computer could do acceptably.

There are many other possible heuristics; choosing links is just an example.

Javadoc doesn't extract much value from its input. Many of the udoc diagnostics could be implemented in javadoc too, and other diagnostic checks added that aren't possible in C++. All of them would improve the documentation output, and many would also help point out bugs in the code.

The input can be HTML, which complicates generating other output formats, limiting the value of the documentation.

Some java concepts are not supported, e.g. evolution of interfaces. During my time at Trolltech, I sorely wished I could make qdoc support interface evolution well. The java designers considered the matter, but did nothing about documentation. Feh.