Comparing javadoc with qdoc and doxygen
Qdoc misses many features Javadoc has. This is intentional — well, mostly. Here's a braindump of the features I dropped or decided against adding.
@author
is one thing Qt had, but I dropped it due to two problems. First, it
misled users who used it to answer the question who should I ask
about this problem?
. The problem was typically about some
recent change to the file, and the original author of the file was the
wrong person to ask. Second, there was some reluctance within the team
about editing someone else's code
, which delayed bugfixes.
I didn't realize at the time, but we once had a real colour of
the bikeshed
discussion about who should be listed as author of
some code. Other aspects of that code warranted lively discussion, but
we actually talked about who should be considered its author.
Doxygen, since it started as a qdoc clone, is mostly identical with qdoc. It does support some javadoc misfeatures, but in every case you can do things the qdoc way.
Qt (qdoc) switched away from a @param-like strategy to an in-sentence tag when I observed that good function documentation doesn't explain parameters separately from the function.
Good function documentation talks about the function, and mentions all the parameters in doing so. Sometimes it also has separate paragraphs for one or more parameters, but it always mentions the parameters in the sentences that describe the function itself. Javadoc's own example talks about both name and url in the documentation for getImage(), and their @param blocks mostly repeat the earlier wording.
Javadoc's @param tag is designed for the sometimes case, whereas I changed qdoc to support the always case instead, and added a warning when you don't do what you always should. In javadoc such a warning would give too many false positives.
The same argument applies (mutatis mutandis) to @return as well. The same javadoc example applies here too.
Creation date (@since) is too simple. There is some value in knowing that a function/class was added in version x.y, but not much. Users who care have to test against the older version anyway, because quite often the function/class has been extended since @since.
Boilerplate like @since is easy to add but often not valuable enough to bother with. Well, unless you want to mask a lack of documentation with bulky boilerplate.
Javadoc's @see is called \sa in qdoc, or it was called \sa until I noticed that whenever I improved a documentation item to the point where I was happy about its quality, the \sa links became unnecessary. Qdoc added the same links on its own volition, based on the documentation text.
@deprecated has potential, but I never found a way to add such a tag that produces better results than just writing an explanation. In my opinion, the java way of doing it is more verbose than Qt's (which uses no syntax, just text), but Qt's resulting documentation is better.
@code is solved very different in qdoc: qdoc knows how to include explanatory code from real source files. Java's approach is susceptible to typoes, missing critical information and other problems like this ghastly example, while qdoc's has the virtues of always providing working, complete source code for all examples, and bidirectionally links each example to the classes and functions it uses.
@link exists in qdoc, and in udoc too, but it's hardly used. Qdoc adds sensible links automatically, so there's little point in typing manual links. The automatic links generally remain meaningful in print, too.
One final item: Included HTML. That's been added to qdoc since I left Trolltech. It can be used to get finegrained control over the HTML documentation, but IMO no documentation is so good that manual HTML work is worth doing. There's always something else that provides better results for the same amount of working time, and it complicates making good PDF files from the documentation.
Any differences not mentioned here may be unintentional, or I may have forgotten about them.