Comparing javadoc with qdoc and doxygen
Qdoc misses many features Javadoc has. This is intentional — javadoc has many naïve or harmful features. 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 notice 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 shows it well: Note how it 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. For example, notice how the function documentation in the javadoc example explains the return value in the first sentence, and then the @return documentation repeats it.
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 such as @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 shows, 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 if you ask me, 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. Send me mail if necessary.